/ Hex Artifact Content
Login

Artifact fac062a139e95b9ea2074518e4de1edceee4b5ff8d3befb2dc51634dc0475b2a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
66c0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
66d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
66e0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
66f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6700: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6710: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6720: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6730: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6740: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6760: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
6770: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
6780: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
6790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
67a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
67b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
67c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
67d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
67e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
67f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
68a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
68b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
68c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
68d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
68e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
68f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
69a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
69b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
69c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
69d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
69e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
69f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
6a60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a80: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
6a90: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6aa0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6ab0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6ac0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6ad0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6ae0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6af0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6b00: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6b10: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6b20: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6b30: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6b40: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
6b50: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
6b60: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
6b70: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
6b80: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
6b90: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6ba0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6bb0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6bc0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6bd0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6be0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6c00: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6c10: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6c20: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6c30: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6c40: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6c50: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6c60: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6c70: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6ca0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6cb0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e  eans that the un
6cc0: 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65  derlying.** file
6cd0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
6ce0: 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77  doing multiple w
6cf0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6d00: 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20  atomically when 
6d10: 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f  those.** write o
6d20: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72  perations are br
6d30: 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49  acketed by [SQLI
6d40: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
6d50: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64  TOMIC_WRITE] and
6d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
6d70: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
6d80: 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69  WRITE]..*/.#defi
6d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6dc0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6df0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6e60: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e80: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6e90: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6eb0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ed0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ee0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6ef0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6f00: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f20: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6f50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6f60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6f70: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6fe0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
7000: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
7010: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
7020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7030: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
7040: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7050: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
7070: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
7080: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
7090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20  P_BATCH_ATOMIC  
70b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34           0x00004
70c0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
70d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
70e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
70f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
7100: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
7110: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7120: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
7130: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
7140: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
7150: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7160: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
7170: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7180: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
71b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
71c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
71d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
71e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
71f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7210: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
7220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7230: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
7240: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7250: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
7260: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
7270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
7280: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
7290: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
72a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
72b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
72d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
72e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
72f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7300: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
7310: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
7320: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7330: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
7340: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
7350: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
7360: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
7370: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
7380: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
7390: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
73a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
73b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
73c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
73d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
73e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
73f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7400: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7410: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7420: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7430: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7440: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7450: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7460: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7470: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7480: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
7490: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
74a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
74b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
74c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
74e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
74f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7500: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7520: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7530: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7540: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7550: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7560: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7570: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7580: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
7590: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
75a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
75b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
75c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
75d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
75e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
75f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7600: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7610: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7620: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7630: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7640: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7650: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7660: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7670: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7680: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
7690: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
76a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
76b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
76c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
76d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
76e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
76f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7700: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7710: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7720: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7730: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7740: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7750: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7770: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7780: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
77a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
77d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
77e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
77f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7800: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7810: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7830: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7840: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7850: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7860: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7870: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7880: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
7890: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
78a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
78b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
78c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
78d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
78e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
78f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7900: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7910: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7930: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7940: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7950: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7960: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7970: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7980: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
7990: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
79a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
79b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
79d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
79e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
79f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7a00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7a20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7a40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7a50: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7a60: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7a70: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a80: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
7a90: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7aa0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7ab0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7ac0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7ad0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7ae0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7af0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7b10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7b20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7b30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7b40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7b50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7b60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7b70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7b80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
7b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7ba0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7bb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7bd0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7be0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7bf0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7c00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7c10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7c20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7c30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7c40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7c50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7c60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7c70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7c80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
7c90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7ca0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7cb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7cc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7cd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7ce0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7cf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7d00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7d10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7d20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7d40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7d50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7d60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7d70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7d80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
7d90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7da0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7db0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7dc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7dd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7de0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7df0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7e00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7e10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7e30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7e40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7e50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7e60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7e70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7e80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7e90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ea0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7eb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ec0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ed0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7ee0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ef0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7f10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7f30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7f50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7f60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7f70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7f80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7f90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7fa0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7fb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7fc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7fe0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7ff0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
8000: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
8010: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
8020: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
8030: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
8040: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
8050: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
8060: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
8070: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
8080: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
8090: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
80a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
80b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
80c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
80d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
80e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
80f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
8100: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
8110: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
8120: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
8130: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8140: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
8150: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
8160: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
8170: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
8180: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
8190: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
81a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
81b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
81c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
81d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
81e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
81f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
8200: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
8210: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
8220: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
8230: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
8240: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
8250: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
8260: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
8270: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
8280: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
8290: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
82a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
82b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
82c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
82d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
82e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
82f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
8300: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
8310: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
8320: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
8330: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
8340: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
8350: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8360: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
8370: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8380: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8390: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
83a0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
83b0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
83c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
83d0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
83e0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
83f0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8400: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8410: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8420: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8430: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8440: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8450: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8460: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8470: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8480: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8490: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
84a0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
84b0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
84c0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
84d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
84e0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
84f0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8500: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8510: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8520: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8530: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8540: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8550: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8560: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8570: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8580: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8590: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
85a0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
85b0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
85c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8610: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8630: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8640: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8650: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8660: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8670: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8690: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
86a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8700: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8710: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8720: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8740: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8750: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8770: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
87a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
87b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
87c0: 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IC].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
9050: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
9060: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
9070: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9080: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
9090: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
90a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
90b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
90c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
90d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
90e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
90f0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
9100: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9110: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
9120: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9180: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9190: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
91a0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
91b0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
91c0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
91d0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
91e0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
91f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
9200: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
9210: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
9220: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
9230: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
9240: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
9250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
9260: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
9270: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
9280: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
9290: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
92a0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
92b0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
92c0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
92d0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
92e0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
92f0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9300: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9320: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9330: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9340: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9350: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9360: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9370: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
9380: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
9390: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93a0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93b0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
93c0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
93d0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
93e0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
93f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9400: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9410: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9420: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9430: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9440: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9450: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9460: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9470: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
9480: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
9490: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94b0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
94c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
94e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
94f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9510: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9520: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9530: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9540: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9550: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9560: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9570: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9580: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9590: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95b0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
95c0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
95d0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
95e0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
95f0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9600: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9610: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9620: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9630: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9640: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9650: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9660: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9670: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9680: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9690: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96a0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96b0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
96c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96d0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
96e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
96f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9700: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9710: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9720: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9740: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9750: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9760: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9770: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9780: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9790: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
97a0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
97c0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
97d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
97e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9800: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9810: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9830: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9840: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9850: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9860: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9870: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9880: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9890: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
98e0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
98f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9900: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9910: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9920: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9950: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9960: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9980: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9990: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
99a0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
99b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
99c0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
99d0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
99e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
99f0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9a00: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9a10: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9a20: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9a30: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9a40: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9a50: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9a60: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9a70: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9a80: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9a90: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9aa0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9ab0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9ac0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9ad0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9ae0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9af0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9b00: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9b10: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9b20: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9b30: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9b40: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9b60: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9b70: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9b80: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9b90: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ba0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9bb0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9bc0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9bd0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9be0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9bf0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9c00: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9c10: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c30: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9c40: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9c50: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9c60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9c70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9c80: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9c90: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9ca0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9cc0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9ce0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9cf0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9d00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9d10: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9d20: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9d30: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9d40: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9d50: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9d60: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9d70: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9d80: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9d90: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9da0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9db0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9dc0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9dd0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9df0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9e00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e10: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9e20: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9e30: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9e40: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9e50: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9e60: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9e70: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ea0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9eb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9ec0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9ed0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9ee0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9ef0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9f00: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9f10: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9f20: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9f30: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9f40: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9f50: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9f60: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9f70: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9f80: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9f90: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9fa0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9fb0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9fc0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9fd0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9fe0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9ff0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a000: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a010: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a020: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a030: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a040: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a050: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a060: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a070: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a080: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a090: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a0a0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a0b0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a0c0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a0d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a0e0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a0f0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a100: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a110: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a120: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a130: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a140: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a150: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a160: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a170: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a180: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a190: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a1a0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a1b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a1c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a1d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a1e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a1f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a200: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a210: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a220: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a230: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a240: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a250: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a260: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a270: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a280: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a290: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a2a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a2b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a2c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a2f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a310: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a320: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a330: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a340: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a350: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a360: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a370: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a380: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a390: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a3a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a3c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a3d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a3e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a3f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a400: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a410: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a420: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a430: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a440: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a450: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a460: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a470: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a480: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a490: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a4a0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a4b0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a4c0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a4d0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a4e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a4f0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a500: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a510: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a520: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a530: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a540: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a550: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a560: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a570: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a580: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a5a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a5b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a5c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a5d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a5e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a5f0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a600: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a610: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a620: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a630: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a640: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a650: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a660: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a670: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a680: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6a0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a6b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a6c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a6d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a6e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a6f0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a700: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a710: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a720: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a730: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a740: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a750: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a760: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a770: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a780: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a790: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a7a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a7b0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a7c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a7e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a7f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a800: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a810: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a820: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a830: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a840: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a850: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a860: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a870: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a880: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a890: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a8a0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a8b0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a8c0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a8d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8e0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a8f0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a910: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a920: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a930: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a940: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a950: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a960: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a970: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a980: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a990: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a9a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9b0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a9c0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a9d0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a9e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a9f0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aa00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aa10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa20: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
aa30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa40: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
aa50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
aa60: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
aa70: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
aa80: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
aa90: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
aaa0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
aab0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
aac0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
aad0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
aae0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aaf0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
ab00: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ab10: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
ab20: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
ab30: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
ab40: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
ab50: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
ab60: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
ab70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
ab80: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
ab90: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
aba0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
abb0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
abc0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
abd0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
abe0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
abf0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
ac00: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
ac10: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
ac20: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
ac30: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
ac40: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
ac50: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
ac60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
ac70: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
ac80: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
ac90: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
aca0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
acb0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
acc0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
acd0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
acf0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
ad00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ad10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
ad20: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
ad30: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ad40: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
ad50: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
ad60: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
ad70: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
ad80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
ad90: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
ada0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
adb0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
adc0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
add0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ade0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
adf0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ae00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ae10: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ae20: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ae30: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ae40: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ae50: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ae60: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ae70: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
ae80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aea0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aeb0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aec0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aee0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aef0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
af00: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
af10: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
af20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
af30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
af40: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
af50: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
af60: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
af70: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
af80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afa0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
afb0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
afc0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
afd0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
afe0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
aff0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b010: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b020: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b030: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b040: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b050: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b060: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b070: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b080: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b0a0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b0b0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b0c0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b0d0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b0e0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b0f0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b100: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b110: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b120: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b130: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b140: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b160: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b170: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b180: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b190: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b1a0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b1b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b1d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b1e0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b1f0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b200: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b210: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b230: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b240: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b250: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b260: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b270: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b280: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b290: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b2a0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b2b0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b2c0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b2d0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b2e0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b2f0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b300: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b310: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b320: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b330: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b340: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b360: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b370: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b380: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b390: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b3a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b3b0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b3c0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b3d0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b3e0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b3f0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b400: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b410: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b420: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b430: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b450: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b460: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b470: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b480: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b490: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b4a0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b4b0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b4c0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b4d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b4e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b500: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b510: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b520: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b530: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b540: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b560: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b570: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b580: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b590: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b5a0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b5b0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b5c0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b5d0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b5e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b5f0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b600: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b610: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b620: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b630: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b640: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b650: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b660: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b670: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b680: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b690: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b6a0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b6b0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b6c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b6d0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b6e0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b6f0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b700: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b710: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b720: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b730: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b740: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b750: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b760: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b770: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b780: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b790: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b7a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b7b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b7c0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b7d0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b7f0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b800: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b810: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b820: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b830: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b840: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b850: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b860: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b870: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b880: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b890: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b8a0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b8b0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b8c0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b8d0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b8e0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b8f0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b900: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b910: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b920: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b930: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b940: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b950: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b960: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b970: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b980: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b9e0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b9f0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ba00: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ba10: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ba20: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ba30: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ba40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ba50: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
ba60: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
ba70: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
ba80: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ba90: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
baa0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bab0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bac0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bad0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bae0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
baf0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bb00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bb10: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bb20: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
bb30: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
bb40: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
bb50: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
bb60: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
bb70: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
bb80: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
bb90: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
bba0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
bbb0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
bbc0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
bbd0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
bbe0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
bbf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc00: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
bc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
bc30: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
bc40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
bc50: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
bc60: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
bc70: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
bc80: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
bc90: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
bca0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bcb0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
bcc0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
bcd0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
bce0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
bcf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
bd00: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
bd10: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
bd20: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
bd30: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
bd40: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
bd50: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
bd70: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
bd80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bd90: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bdc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bdd0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bdf0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
be00: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
be10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
be20: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
be30: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
be40: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
be50: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
be60: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
be70: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
be80: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
be90: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bea0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
beb0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bee0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf00: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bf10: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bf20: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bf30: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bf40: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bf50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bf60: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bf70: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bf80: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf90: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bfa0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bfb0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bfc0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bfd0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bfe0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c000: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c010: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c030: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c040: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c050: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c060: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c070: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c080: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c090: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c0a0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c0b0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c0c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c0d0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c0e0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c0f0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c100: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c110: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c120: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c130: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c150: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c170: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c180: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c190: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c1a0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c1b0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c1c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c1d0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c1e0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c1f0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c200: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c210: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c220: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c230: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c240: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c250: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c260: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c270: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c290: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c2a0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c2b0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c2c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c2d0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c2f0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c300: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c310: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c320: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c330: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c340: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c350: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c390: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c3a0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c3b0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c3c0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c3d0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c3e0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c3f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c400: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c410: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c420: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c440: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c450: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c470: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c480: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c490: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c4a0: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c4b0: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c4c0: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c4d0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c4e0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c4f0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c500: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c510: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c520: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
c530: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
c540: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c550: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
c560: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
c570: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
c580: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
c590: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
c5a0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
c5b0: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
c5c0: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
c5d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c5e0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
c5f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
c600: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
c610: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c620: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
c640: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
c650: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
c660: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
c670: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
c680: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
c690: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
c6a0: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
c6b0: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
c6c0: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
c6d0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
c6e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
c6f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
c700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
c710: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c720: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
c740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c750: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c760: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
c770: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
c780: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
c790: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
c7a0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
c7b0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
c7c0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c7d0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
c7e0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
c7f0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
c810: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
c820: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c830: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
c840: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
c850: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
c860: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
c870: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
c880: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
c890: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
c8a0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
c8b0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
c8c0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c8d0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
c8e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
c8f0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
c900: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
c910: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
c920: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
c930: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
c940: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
c950: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
c960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c970: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
c980: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
c990: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
c9a0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
c9b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c9c0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
c9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c9e0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c9f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ca00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
ca10: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
ca20: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
ca30: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
ca40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
ca50: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
ca60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ca70: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
ca80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ca90: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
caa0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cab0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cac0: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cad0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cae0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
caf0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cb00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cb10: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cb20: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
cb30: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
cb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
cb50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
cb70: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
cb80: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
cb90: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
cba0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cbb0: 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  WRITE]..**.** <l
cbc0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
cbd0: 5f 52 45 41 44 5f 53 48 4d 5d 5d 0a 2a 2a 20 54  _READ_SHM]].** T
cbe0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cbf0: 5f 52 45 41 44 5f 53 48 4d 5d 20 6f 70 63 6f 64  _READ_SHM] opcod
cc00: 65 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  e may be used to
cc10: 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20   read data from 
cc20: 0a 2a 2a 20 74 68 65 20 73 68 61 72 65 64 2d 6d  .** the shared-m
cc30: 65 6d 6f 72 79 20 72 65 67 69 6f 6e 20 75 73 65  emory region use
cc40: 64 20 62 79 20 77 61 6c 20 6d 6f 64 65 20 69 66  d by wal mode if
cc50: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
cc60: 6c 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 68  ll.** to the xSh
cc70: 6d 4d 61 70 20 6d 65 74 68 6f 64 20 72 65 74 75  mMap method retu
cc80: 72 6e 65 64 20 53 51 4c 49 54 45 5f 52 45 41 44  rned SQLITE_READ
cc90: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 2e 20 54  ONLY_CANTLOCK. T
cca0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6d  he argument.** m
ccb0: 75 73 74 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  ust point to an 
ccc0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 73 74  instance of a st
ccd0: 72 75 63 74 75 72 65 20 64 65 63 6c 61 72 65 64  ructure declared
cce0: 20 61 73 3a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75   as:.** <blockqu
ccf0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 73  ote><pre>.**   s
cd00: 74 72 75 63 74 20 52 65 61 64 53 68 6d 41 72 67  truct ReadShmArg
cd10: 20 7b 20 76 6f 69 64 20 2a 70 42 75 66 3b 20 69   { void *pBuf; i
cd20: 6e 74 20 6e 42 75 66 20 7d 3b 0a 2a 2a 20 3c 2f  nt nBuf };.** </
cd30: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
cd40: 3e 29 5e 0a 2a 2a 20 42 65 66 6f 72 65 20 72 65  >)^.** Before re
cd50: 74 75 72 6e 69 6e 67 2c 20 74 68 69 73 20 6f 70  turning, this op
cd60: 65 72 61 74 69 6f 6e 20 61 6c 6c 6f 63 61 74 65  eration allocate
cd70: 73 20 61 20 62 75 66 66 65 72 20 6c 61 72 67 65  s a buffer large
cd80: 20 65 6e 6f 75 67 68 20 66 6f 72 0a 2a 2a 20 74   enough for.** t
cd90: 68 65 20 65 6e 74 69 72 65 20 73 68 61 72 65 64  he entire shared
cda0: 2d 6d 65 6d 6f 72 79 20 75 73 69 6e 67 20 73 71  -memory using sq
cdb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
cdc0: 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 69 74 20  nd populates it 
cdd0: 77 69 74 68 0a 2a 2a 20 61 20 63 6f 70 79 20 74  with.** a copy t
cde0: 68 65 72 65 6f 66 2e 20 52 65 61 64 53 68 6d 41  hereof. ReadShmA
cdf0: 72 67 2e 70 42 75 66 20 69 73 20 73 65 74 20 74  rg.pBuf is set t
ce00: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 62  o point to the b
ce10: 75 66 66 65 72 2c 20 61 6e 64 0a 2a 2a 20 52 65  uffer, and.** Re
ce20: 61 64 53 68 6d 41 72 67 20 74 6f 20 69 74 73 20  adShmArg to its 
ce30: 73 69 7a 65 20 69 6e 20 62 79 74 65 73 2e 20 49  size in bytes. I
ce40: 74 20 69 73 20 74 68 65 20 72 65 73 70 6f 6e 73  t is the respons
ce50: 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20 63  ibility of the c
ce60: 61 6c 6c 65 72 0a 2a 2a 20 74 6f 20 65 76 65 6e  aller.** to even
ce70: 74 75 61 6c 6c 79 20 66 72 65 65 20 74 68 65 20  tually free the 
ce80: 62 75 66 66 65 72 20 75 73 69 6e 67 20 73 71 6c  buffer using sql
ce90: 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 20  ite3_free()..** 
cea0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
ceb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
cec0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
ced0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
cee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
cef0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
cf00: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
cf10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
cf20: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cf30: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
cf40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
cf50: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
cf60: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
cf70: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
cf80: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
cf90: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
cfa0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
cfb0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
cfc0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
cfd0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
cfe0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
cff0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
d000: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
d010: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
d020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d030: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
d040: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
d050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d060: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
d070: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
d080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d090: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
d0a0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
d0b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d0c0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
d0d0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
d0e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0f0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
d100: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
d110: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d120: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
d130: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
d140: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d150: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
d160: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
d170: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
d180: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
d190: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
d1a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
d1b0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
d1c0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
d1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
d1e0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
d1f0: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
d200: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
d210: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
d220: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
d230: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
d240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d250: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
d260: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
d270: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
d280: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
d290: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
d2a0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
d2b0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
d2c0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
d2d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
d2e0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d2f0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
d300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
d310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d320: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
d330: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
d340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d350: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
d360: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
d370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d380: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
d390: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64  TER        28.#d
d3a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d3b0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
d3c0: 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65  DLE       29.#de
d3d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d3e0: 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20  L_PDB           
d3f0: 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66           30.#def
d400: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d410: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
d420: 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69  ITE     31.#defi
d430: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d440: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
d450: 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  ITE    32.#defin
d460: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
d470: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
d480: 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e 65  RITE  33.#define
d490: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 45   SQLITE_FCNTL_RE
d4a0: 41 44 5f 53 48 4d 20 20 20 20 20 20 20 20 20 20  AD_SHM          
d4b0: 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70 72       34../* depr
d4c0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
d4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
d4e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d4f0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
d500: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d510: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
d520: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
d530: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
d540: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
d550: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
d560: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
d570: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d580: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
d590: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
d5a0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
d5b0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
d5c0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
d5d0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
d5e0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
d5f0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
d600: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
d610: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
d620: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
d630: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
d640: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
d650: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
d660: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d670: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
d680: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
d690: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
d6a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
d6b0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
d6c0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
d6d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d6e0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
d6f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d700: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
d710: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
d720: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d730: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
d740: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
d750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d760: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
d770: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
d780: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
d790: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
d7a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
d7b0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
d7c0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
d7d0: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
d7e0: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
d7f0: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
d800: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
d810: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
d820: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
d830: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
d840: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
d850: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d860: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
d870: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
d880: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
d890: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
d8a0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d8b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d8c0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
d8d0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
d8e0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
d8f0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
d900: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
d910: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
d920: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
d930: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
d940: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
d950: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
d960: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
d970: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
d980: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
d990: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
d9a0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
d9b0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
d9c0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
d9d0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
d9e0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
d9f0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
da00: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
da10: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
da20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
da30: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
da40: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
da50: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
da60: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
da70: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
da80: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
da90: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
daa0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
dab0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
dac0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
dad0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
dae0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
daf0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
db00: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
db10: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
db20: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
db30: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
db40: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
db50: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
db60: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
db70: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
db80: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
db90: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
dba0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
dbb0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
dbc0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
dbd0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
dbe0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
dbf0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
dc00: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
dc10: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
dc20: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
dc30: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
dc40: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
dc50: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
dc60: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
dc70: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
dc80: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
dc90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
dca0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
dcb0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
dcc0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
dcd0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
dce0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
dcf0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
dd00: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
dd10: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dd20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
dd30: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
dd40: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
dd50: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
dd60: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
dd70: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
dd80: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
dd90: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
dda0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
ddb0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
ddc0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
ddd0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
dde0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
ddf0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
de00: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
de10: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
de20: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
de30: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
de40: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
de50: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
de60: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
de70: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
de80: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
de90: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
dea0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
deb0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
dec0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
ded0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
dee0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
def0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
df00: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
df10: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
df20: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
df30: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
df40: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
df50: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
df60: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
df70: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
df80: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
df90: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
dfa0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
dfb0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
dfc0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
dfd0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
dfe0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
dff0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
e000: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
e010: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
e020: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
e030: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
e040: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
e050: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
e060: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
e070: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
e080: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
e090: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
e0a0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
e0b0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
e0c0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
e0d0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
e0e0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
e0f0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
e100: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
e110: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
e120: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
e130: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
e140: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e150: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
e160: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
e170: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
e180: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
e190: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
e1a0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
e1b0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
e1c0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
e1d0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
e1e0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
e1f0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
e200: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
e210: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
e220: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e230: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
e240: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
e250: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
e260: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
e270: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
e280: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
e290: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
e2a0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
e2b0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
e2c0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
e2d0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
e2e0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
e2f0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
e300: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
e310: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
e320: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
e330: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
e340: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
e350: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
e360: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
e370: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
e380: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
e390: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
e3a0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
e3b0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
e3c0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
e3d0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e3e0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e3f0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
e400: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
e410: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
e420: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
e430: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
e440: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
e450: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e460: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
e470: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
e480: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
e490: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
e4b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e4c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
e4d0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
e4e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e4f0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
e500: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e510: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
e520: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e530: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
e540: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
e550: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
e560: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
e570: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
e580: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
e590: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
e5a0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
e5b0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
e5c0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
e5d0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
e5e0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
e5f0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
e600: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
e610: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
e620: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
e630: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
e640: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
e650: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
e660: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
e670: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
e680: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
e690: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
e6a0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
e6b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
e6c0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
e6d0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
e6e0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
e6f0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
e700: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
e710: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
e720: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
e730: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
e740: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
e750: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
e760: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
e770: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e780: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e790: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e7a0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
e7b0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
e7c0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e7d0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
e7e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
e7f0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
e800: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
e810: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
e820: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
e830: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
e840: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
e850: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
e860: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
e870: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
e880: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
e890: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
e8a0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
e8b0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
e8c0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
e8d0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
e8e0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
e8f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
e900: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
e910: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
e920: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
e930: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e940: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
e950: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
e960: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
e970: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
e980: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
e990: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
e9a0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
e9b0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
e9c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
e9d0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
e9e0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
e9f0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
ea00: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
ea10: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
ea20: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
ea30: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
ea40: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
ea50: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
ea60: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
ea70: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
ea80: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
ea90: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
eaa0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
eab0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
eac0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
ead0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
eae0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
eaf0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
eb00: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
eb10: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
eb20: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
eb30: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
eb40: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
eb50: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
eb60: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
eb70: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
eb80: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
eb90: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
eba0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ebb0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ebc0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
ebd0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
ebe0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
ebf0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
ec00: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
ec10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
ec20: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
ec30: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
ec40: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
ec50: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
ec60: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
ec70: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
ec80: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
ec90: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
eca0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
ecb0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
ecc0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
ecd0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
ece0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
ecf0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
ed00: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
ed10: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
ed20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
ed30: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
ed40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
ed50: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
ed60: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
ed70: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
ed80: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
ed90: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
eda0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
edb0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
edc0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
edd0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
ede0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
edf0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
ee00: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
ee10: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
ee20: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
ee30: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
ee40: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
ee50: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
ee60: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
ee70: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
ee80: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
ee90: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
eea0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
eeb0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
eec0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
eed0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
eee0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
eef0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
ef00: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ef10: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
ef20: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
ef30: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
ef40: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
ef50: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
ef60: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
ef70: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
ef80: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
ef90: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
efa0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
efb0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
efc0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
efd0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
efe0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
eff0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
f000: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
f010: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
f020: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
f030: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
f040: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
f050: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
f060: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
f070: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
f080: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
f090: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
f0a0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
f0b0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
f0c0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
f0d0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
f0e0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
f0f0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
f100: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
f110: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
f120: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
f130: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
f140: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
f150: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
f160: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
f170: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
f180: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
f190: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
f1a0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
f1b0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
f1c0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
f1d0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
f1e0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
f1f0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
f200: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
f210: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
f220: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
f230: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
f240: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
f250: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
f260: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
f270: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
f280: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
f290: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
f2a0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
f2b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
f2c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
f2d0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
f2e0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
f2f0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
f300: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
f310: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
f320: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
f330: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
f340: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
f350: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
f360: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
f370: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
f380: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
f390: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
f3a0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
f3b0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
f3c0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
f3d0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
f3e0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
f3f0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
f400: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
f410: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
f420: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
f430: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
f440: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
f450: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
f460: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
f470: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f480: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
f490: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
f4a0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
f4b0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
f4c0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
f4d0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
f4e0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
f4f0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
f500: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
f510: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
f520: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
f530: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
f540: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
f550: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
f560: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
f570: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
f580: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
f590: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
f5a0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
f5b0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
f5c0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
f5d0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
f5e0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
f5f0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
f600: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
f610: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
f620: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
f630: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
f640: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
f650: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
f660: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
f670: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
f680: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
f690: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
f6a0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
f6b0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
f6c0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
f6d0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
f6e0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
f6f0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
f700: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
f710: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
f720: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
f730: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
f740: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
f750: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
f760: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
f770: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
f780: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
f790: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
f7a0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
f7b0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
f7c0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
f7d0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
f7e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
f7f0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
f800: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
f810: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
f820: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
f830: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
f840: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
f850: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
f860: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
f870: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
f880: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
f890: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
f8a0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
f8b0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
f8c0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
f8d0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
f8e0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
f8f0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
f900: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
f910: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
f920: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f930: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
f940: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
f950: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
f960: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
f970: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
f980: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
f990: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f9a0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
f9b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
f9c0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
f9d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f9e0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
f9f0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
fa00: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
fa10: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
fa20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
fa30: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
fa40: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
fa50: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
fa60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fa70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
fa80: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
fa90: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
faa0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
fab0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
fac0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
fad0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
fae0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
faf0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
fb00: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
fb10: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
fb20: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
fb30: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
fb40: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
fb50: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
fb60: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
fb70: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
fb80: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
fb90: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
fba0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
fbb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fbc0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
fbd0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
fbe0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fbf0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
fc00: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
fc10: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
fc20: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
fc30: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
fc40: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
fc50: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
fc60: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
fc70: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
fc80: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
fc90: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
fca0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
fcb0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
fcc0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
fcd0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fce0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fcf0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
fd00: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
fd10: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
fd20: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
fd30: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
fd40: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
fd50: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
fd60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fd70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fd80: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
fd90: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
fda0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
fdb0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
fdc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fdd0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
fde0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
fdf0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
fe00: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
fe10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
fe20: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
fe30: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
fe40: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
fe50: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
fe60: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
fe70: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
fe80: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
fe90: 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
fea0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
feb0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
fec0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
fed0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
fee0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
fef0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
ff00: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
ff10: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
ff20: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
ff30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
ff40: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
ff50: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
ff60: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
ff70: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
ff80: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
ff90: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
ffa0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
ffb0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
ffc0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
ffd0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
ffe0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
fff0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
10000 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
10010 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
10020 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
10030 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
10040 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
10050 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10060 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
10070 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
10080 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
10090 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
100a0 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
100b0 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
100c0 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
100d0 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
100e0 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
100f0 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
10100 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
10110 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
10120 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10130 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
10140 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
10150 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
10160 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
10170 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
10180 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
10190 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
101a0 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
101b0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
101c0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
101d0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
101e0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
101f0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
10200 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
10210 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
10220 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
10230 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
10240 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
10250 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
10260 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
10270 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
10280 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
10290 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
102a0 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
102b0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
102c0 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
102d0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
102e0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
102f0 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
10300 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10310 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
10320 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
10330 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
10340 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
10350 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
10360 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
10370 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
10380 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
10390 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
103a0 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
103b0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
103c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
103d0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
103e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
103f0 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
10400 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
10410 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
10420 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
10430 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
10440 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
10450 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10460 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10470 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10480 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10490 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
104a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
104b0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
104c0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
104d0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
104e0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
104f0 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
10500 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
10510 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
10520 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
10530 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
10540 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
10550 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
10560 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
10570 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
10580 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10590 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
105a0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
105b0 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
105c0 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
105d0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
105e0 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
105f0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10600 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
10610 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
10620 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10630 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
10640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10650 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
10660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10670 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
10680 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
10690 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
106a0 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
106b0 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
106c0 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
106d0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
106e0 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
106f0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
10700 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
10710 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
10720 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
10730 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
10740 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
10750 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
10760 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
10770 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
10780 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
10790 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
107a0 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
107b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
107c0 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
107d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
107e0 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
107f0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
10800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10810 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10820 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
10830 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
10840 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
10850 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
10860 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
10870 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
10880 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
10890 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
108a0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
108b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
108c0 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
108d0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
108e0 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
108f0 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
10900 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
10910 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
10920 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
10930 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
10940 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
10950 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
10960 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
10970 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
10980 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10990 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
109a0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
109b0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
109c0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
109d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
109e0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
109f0 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
10a00 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
10a10 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
10a20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
10a30 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10a40 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
10a50 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
10a60 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10a70 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
10a80 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
10a90 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
10aa0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10ab0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
10ac0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
10ad0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
10ae0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10af0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
10b00 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10b10 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
10b20 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
10b30 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10b40 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
10b50 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10b60 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
10b70 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10b80 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
10b90 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10ba0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
10bb0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
10bc0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
10bd0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
10be0 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
10bf0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10c00 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
10c10 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10c20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10c30 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
10c40 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
10c50 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
10c60 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
10c70 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
10c80 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
10c90 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
10ca0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
10cb0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
10cc0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
10cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10ce0 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
10cf0 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
10d00 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
10d10 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
10d20 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
10d30 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
10d40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10d50 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
10d60 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
10d70 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d80 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
10d90 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10da0 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
10db0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
10dc0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
10dd0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
10de0 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
10df0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10e00 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10e10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10e20 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10e30 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10e40 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10e50 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
10e60 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
10e70 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
10e80 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
10e90 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
10ea0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
10eb0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
10ec0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
10ed0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
10ee0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
10ef0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
10f00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10f10 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10f20 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10f30 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10f40 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10f50 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
10f60 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
10f70 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
10f80 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
10f90 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
10fa0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10fb0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
10fc0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
10fd0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
10fe0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10ff0 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
11000 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
11010 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
11020 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
11030 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
11040 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
11050 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
11060 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
11070 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
11080 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
11090 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
110a0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
110b0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
110c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
110d0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
110e0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
110f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
11100 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
11110 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
11120 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
11130 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11140 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
11150 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
11160 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
11170 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
11180 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
11190 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
111a0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
111b0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
111c0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
111d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
111e0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
111f0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11200 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11210 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
11220 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
11230 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
11240 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
11250 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
11260 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
11270 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11280 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
11290 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
112a0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
112b0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
112c0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
112d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
112e0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
112f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
11300 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
11310 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
11320 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
11330 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11340 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
11350 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
11360 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
11370 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
11380 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
11390 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
113a0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
113b0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
113c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
113d0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
113e0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
113f0 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
11400 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
11410 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
11420 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
11430 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
11440 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
11450 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
11460 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
11470 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
11480 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
11490 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
114a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
114b0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
114c0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
114d0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
114e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
114f0 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
11500 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
11510 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
11520 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11530 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11540 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11550 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
11560 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
11570 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
11580 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
11590 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
115a0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
115b0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
115c0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
115d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
115e0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
115f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
11600 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
11610 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
11620 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11630 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
11640 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
11650 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
11660 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
11670 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
11680 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
11690 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
116a0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
116b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
116c0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
116d0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
116e0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
116f0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
11700 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
11710 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
11720 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11730 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11740 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
11750 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
11760 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
11770 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
11780 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
11790 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
117a0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
117b0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
117c0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
117d0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
117e0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
117f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
11800 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
11810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
11820 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
11830 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11840 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
11850 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
11860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11870 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
11880 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11890 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
118a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
118b0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
118c0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
118d0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
118e0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
118f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
11900 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
11910 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
11920 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
11930 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
11940 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
11950 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11960 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
11970 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
11980 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
11990 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
119a0 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
119b0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
119c0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
119d0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
119e0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
119f0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f   <b>The sqlite3_
11a00 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11a10 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
11a20 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63  safe. The applic
11a30 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
11a40 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
11a50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11a60 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
11a70 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
11a80 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
11a90 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
11aa0 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a  unning.</b>.**.*
11ab0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
11ac0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11ad0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
11ae0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
11af0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
11b00 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
11b10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11b20 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
11b30 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
11b40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11b50 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
11b60 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
11b70 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
11b80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11b90 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
11ba0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11bb0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
11bc0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
11bd0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
11be0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
11bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11c00 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
11c10 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
11c20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11c30 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
11c40 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
11c50 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
11c60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11c70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11c80 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
11c90 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
11ca0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11cb0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
11cc0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
11cd0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
11ce0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
11cf0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
11d00 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
11d10 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11d20 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
11d30 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
11d40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11d50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
11d60 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
11d70 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
11d80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11d90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11da0 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
11db0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
11dc0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
11dd0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
11de0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
11df0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
11e00 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
11e10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
11e20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
11e30 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
11e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11e50 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
11e60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
11e70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
11e80 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
11e90 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11ea0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
11eb0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
11ec0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
11ed0 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
11ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
11ef0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
11f00 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
11f10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11f20 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
11f30 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
11f40 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
11f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11f60 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
11f70 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11f80 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
11f90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11fa0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
11fb0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
11fc0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
11fd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11fe0 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
11ff0 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
12000 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
12010 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
12020 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
12030 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
12040 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
12050 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
12060 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
12070 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
12080 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
12090 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
120a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
120b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
120c0 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
120d0 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
120e0 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
120f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
12100 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e  uccessful..*/.in
12110 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
12120 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
12130 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
12140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
12150 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
12160 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
12170 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
12180 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
12190 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
121a0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
121b0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
121c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
121d0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
121e0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
121f0 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
12200 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
12210 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
12220 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
12230 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12240 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
12250 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
12260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12270 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
12280 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12290 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
122a0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
122b0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
122c0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
122d0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
122e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
122f0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
12300 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
12310 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
12320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12330 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
12340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
12350 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
12360 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
12370 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12390 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
123a0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
123b0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
123c0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
123d0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
123e0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
123f0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
12400 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
12410 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
12420 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
12430 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
12440 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
12450 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
12460 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
12470 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
12480 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
12490 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
124a0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
124b0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
124c0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
124d0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
124e0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
124f0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
12500 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
12510 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
12520 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
12530 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
12540 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12550 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
12560 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
12570 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
12580 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
12590 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
125a0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
125b0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
125c0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
125d0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
125e0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
125f0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
12600 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
12610 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
12620 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
12630 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
12640 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12650 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
12660 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
12670 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
12680 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
12690 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
126a0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
126b0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
126c0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
126d0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
126e0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
126f0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
12700 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12710 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
12720 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
12730 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
12740 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
12750 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
12760 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
12770 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
12780 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
12790 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
127a0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
127b0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
127c0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
127d0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
127e0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
127f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
12800 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
12810 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
12820 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
12830 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12840 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
12850 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
12860 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
12870 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
12880 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
12890 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
128a0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
128b0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
128c0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
128d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
128e0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
128f0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
12900 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
12910 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12920 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
12930 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
12940 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
12950 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
12960 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12970 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
12980 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
12990 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
129a0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
129b0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
129c0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
129d0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
129e0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
129f0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
12a00 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
12a10 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
12a20 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
12a30 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12a40 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
12a50 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
12a60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12a70 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
12a80 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
12a90 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
12aa0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
12ab0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
12ac0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
12ad0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
12ae0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
12af0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
12b00 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
12b10 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
12b20 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
12b30 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
12b40 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
12b50 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
12b60 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
12b70 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
12b80 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
12b90 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12ba0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
12bb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
12bc0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
12bd0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
12be0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
12bf0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
12c00 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
12c10 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
12c20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
12c30 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
12c40 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
12c50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
12c60 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
12c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12c80 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
12c90 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
12ca0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
12cb0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
12cc0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
12cd0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
12ce0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
12cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12d00 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
12d10 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
12d20 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
12d30 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
12d40 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
12d50 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
12d60 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
12d70 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
12d80 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
12d90 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
12da0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
12db0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
12dc0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
12dd0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
12de0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
12df0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12e00 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
12e10 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
12e20 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12e30 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
12e40 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
12e50 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
12e60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12e70 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
12e80 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
12e90 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
12ea0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
12eb0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
12ec0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
12ed0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
12ee0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
12ef0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
12f00 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
12f10 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
12f20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
12f30 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12f40 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
12f50 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
12f60 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
12f70 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
12f80 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
12f90 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
12fa0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
12fb0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
12fc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12fd0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
12fe0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
12ff0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
13000 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13010 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13020 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
13030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
13040 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
13050 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
13060 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
13070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13080 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
13090 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
130a0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
130b0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
130c0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
130d0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
130e0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
130f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
13100 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
13110 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
13120 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
13130 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13140 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
13150 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
13160 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
13170 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
13180 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
13190 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
131a0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
131b0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
131c0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
131d0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
131e0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
131f0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
13200 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
13210 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
13220 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
13230 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
13240 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13250 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
13260 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
13270 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13280 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
13290 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
132a0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
132b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
132c0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
132d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
132e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
132f0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
13300 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13310 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
13320 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
13330 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
13340 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
13350 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
13360 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
13370 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
13380 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
13390 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
133a0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
133b0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
133c0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
133d0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
133e0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
133f0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
13400 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
13410 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13420 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13430 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13440 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13450 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13460 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13470 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13480 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
13490 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
134a0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
134b0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
134c0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
134d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
134e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
134f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13500 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
13510 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13520 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13530 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13540 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13550 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13560 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13580 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13590 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
135a0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
135b0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
135c0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
135d0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
135e0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
135f0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
13600 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13610 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13620 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
13630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13640 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13650 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
13660 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
13670 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
13680 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
13690 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
136a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
136b0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
136c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
136d0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
136e0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
136f0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
13710 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
13720 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
13730 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
13740 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
13750 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
13760 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
13770 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13780 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
13790 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
137a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
137b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
137c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
137d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
137e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
137f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13800 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13810 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
13820 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
13830 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13840 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
13850 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13860 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13870 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13880 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
13890 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
138a0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
138b0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
138c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
138d0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
138e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
138f0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
13900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13910 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13920 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13930 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13940 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13950 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13960 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
13970 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
13980 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
13990 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
139a0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
139b0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
139c0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
139d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
139e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
139f0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13a00 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
13a10 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
13a20 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
13a30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13a40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
13a50 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
13a60 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
13a70 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
13a80 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
13a90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13aa0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
13ab0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
13ac0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
13ad0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
13ae0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
13af0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
13b00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
13b10 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
13b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13b30 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
13b40 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
13b50 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
13b60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13b70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13b80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13b90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13ba0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13bb0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13bc0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13bd0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
13be0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
13bf0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13c10 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13c20 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13c30 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13c40 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13c50 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
13c60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13c70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13c80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13c90 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13cb0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13cc0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13cd0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
13ce0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13cf0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13d00 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
13d10 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13d20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13d30 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13d40 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
13d50 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13d60 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
13d70 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
13d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13d90 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
13da0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
13db0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13dc0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
13dd0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
13de0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
13df0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
13e00 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
13e10 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13e20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13e30 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
13e40 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
13e50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13e60 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
13e70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13e90 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13ea0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13eb0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
13ec0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13ed0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
13ee0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13ef0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13f00 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
13f10 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13f20 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13f30 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13f40 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
13f50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13f60 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13f70 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13f80 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13f90 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
13fa0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13fb0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
13fc0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
13fd0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
13fe0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
13ff0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14000 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14010 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
14020 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
14030 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
14040 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
14050 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
14060 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
14070 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14080 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
14090 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
140a0 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
140b0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
140c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
140d0 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20  IG_SMALL_MALLOC 
140e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
140f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a  gle argument of.
14100 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  ** type int, int
14110 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
14120 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20  olean, which if 
14130 74 72 75 65 20 70 72 6f 76 69 64 65 73 20 61 20  true provides a 
14140 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74  hint to.** SQLit
14150 65 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64  e that it should
14160 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d   avoid large mem
14170 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
14180 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  if possible..** 
14190 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20  SQLite will run 
141a0 66 61 73 74 65 72 20 69 66 20 69 74 20 69 73 20  faster if it is 
141b0 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72  free to make lar
141c0 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ge memory alloca
141d0 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f  tions,.** but so
141e0 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  me application m
141f0 69 67 68 74 20 70 72 65 66 65 72 20 74 6f 20 72  ight prefer to r
14200 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63  un slower in exc
14210 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61  hange for.** gua
14220 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65  rantees about me
14230 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69  mory fragmentati
14240 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73 73  on that are poss
14250 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a  ible if large.**
14260 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65   allocations are
14270 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20   avoided.  This 
14280 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  hint is normally
14290 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   off..** </dd>.*
142a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
142b0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
142c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
142d0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
142e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
142f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14300 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
14310 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
14320 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
14330 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
14340 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
14350 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
14360 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
14370 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
14380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14390 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
143a0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
143b0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
143c0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
143d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
143e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
143f0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
14400 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
14410 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
14420 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14430 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14440 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
14450 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
14460 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
14470 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
14480 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14490 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
144a0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
144b0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
144c0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
144d0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
144e0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
144f0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
14500 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
14510 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
14520 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
14530 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
14540 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14550 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
14560 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
14570 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14590 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
145a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
145b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
145c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
145d0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73  CRATCH option is
145e0 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e   no longer used.
145f0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14600 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14610 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
14620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14630 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
14640 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14650 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14660 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  E option specifi
14670 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c  es a memory pool
14680 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
14690 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
146a0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
146b0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
146c0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
146d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
146e0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
146f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14700 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20  n is a no-op if 
14710 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
14720 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
14730 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14740 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
14750 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
14760 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a  ONFIG_PCACHE2]..
14770 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14780 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14790 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
147a0 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
147b0 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
147c0 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
147d0 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65  (pMem), the size
147e0 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61   of each page ca
147f0 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a  che line (sz),.*
14800 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  * and the number
14810 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20   of cache lines 
14820 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
14830 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
14840 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
14850 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
14860 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
14870 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
14880 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36  en 512 and 65536
14890 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72  ) plus some extr
148a0 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68  a bytes for each
148b0 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
148c0 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66    ^The number of
148d0 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65   extra bytes nee
148e0 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ded by the page 
148f0 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65  header.** can be
14900 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
14910 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  g [SQLITE_CONFIG
14920 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a  _PCACHE_HDRSZ]..
14930 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  ** ^It is harmle
14940 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
14950 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
14960 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20  ,.** for the sz 
14970 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
14980 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65  larger than nece
14990 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d  ssary.  The pMem
149a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
149b0 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
149c0 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20  LL pointer or a 
149d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
149e0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
149f0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
14a00 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
14a10 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73   bytes, otherwis
14a20 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  e.** subsequent 
14a30 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
14a40 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fined..** ^When 
14a50 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  pMem is not NULL
14a60 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74  , SQLite will st
14a70 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20  rive to use the 
14a80 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a  memory provided.
14a90 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61  ** to satisfy pa
14aa0 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20  ge cache needs, 
14ab0 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20  falling back to 
14ac0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14ad0 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20  )] if.** a page 
14ae0 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61  cache line is la
14af0 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74  rger than sz byt
14b00 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20  es or if all of 
14b10 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a  the pMem buffer.
14b20 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ** is exhausted.
14b30 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20  .** ^If pMem is 
14b40 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f  NULL and N is no
14b50 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63  n-zero, then eac
14b60 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14b70 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e  ction.** does an
14b80 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c   initial bulk al
14b90 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67  location for pag
14ba0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a  e cache memory.*
14bb0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
14bc0 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63  malloc()] suffic
14bd0 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65  ient for N cache
14be0 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70   lines if N is p
14bf0 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66  ositive or.** of
14c00 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69   -1024*N bytes i
14c10 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  f N is negative,
14c20 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61   . ^If additiona
14c30 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
14c40 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
14c50 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
14c60 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
14c70 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63  initial.** alloc
14c80 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69  ation, then SQLi
14c90 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
14ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65  te3_malloc()] se
14cb0 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63  parately for eac
14cc0 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  h.** additional 
14cd0 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64  cache line. </dd
14ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14cf0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
14d00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d10 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
14d20 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14d30 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
14d40 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
14d50 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
14d60 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  er .** that SQLi
14d70 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20  te will use for 
14d80 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
14d90 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
14da0 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65  tion needs.** be
14db0 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
14dc0 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  ded for by [SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14de0 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
14df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14e00 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14e10 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
14e20 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
14e30 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
14e40 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
14e50 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
14e60 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
14e70 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
14e80 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
14e90 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
14ea0 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
14eb0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14ec0 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14ed0 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
14ee0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14ef0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
14f00 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
14f10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14f20 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
14f30 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
14f40 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14f50 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
14f60 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14f70 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14f80 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14f90 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14fa0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14fb0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14fc0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14fd0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14fe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14ff0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
15000 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
15010 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
15020 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
15030 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
15040 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15050 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
15060 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
15070 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
15080 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
15090 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
150a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
150b0 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
150c0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
150d0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
150e0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
150f0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
15100 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
15110 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
15120 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
15130 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
15140 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
15150 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
15160 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
15170 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
15180 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
15190 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
151a0 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
151b0 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
151c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
151d0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
151e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
151f0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
15200 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15210 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
15220 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15230 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15240 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
15250 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15260 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15270 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15280 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
15290 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
152a0 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
152b0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
152c0 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
152d0 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
152e0 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
152f0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
15300 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
15310 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
15320 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
15330 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
15340 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15350 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
15360 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
15370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15380 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
15390 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
153a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
153b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
153c0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
153d0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
153e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
153f0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
15400 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
15410 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
15420 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
15430 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
15440 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
15450 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
15460 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15470 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
15480 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
15490 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
154a0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
154b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
154c0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
154d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
154e0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
154f0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15500 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15510 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
15520 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15530 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
15540 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15550 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
15560 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15570 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15580 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
15590 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
155a0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
155b0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
155c0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
155d0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
155e0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
155f0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
15600 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
15610 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
15620 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
15630 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
15640 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
15650 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
15660 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
15670 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
15680 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
15690 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
156a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
156b0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
156c0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
156d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
156e0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
156f0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15700 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
15710 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
15720 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
15730 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
15740 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
15750 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15760 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
15770 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15790 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
157a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
157b0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
157c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
157d0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
157e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
157f0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15800 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15810 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15820 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
15830 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
15840 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
15850 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
15860 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
15870 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
15880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15890 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
158a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
158b0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
158c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
158d0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
158e0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
158f0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
15900 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
15910 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
15920 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
15930 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15940 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
15950 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
15960 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
15970 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
15980 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
15990 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
159a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
159b0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
159c0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
159d0 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
159e0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
159f0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
15a00 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15a10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15a20 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15a40 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
15a50 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15a60 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
15a70 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15a80 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15a90 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
15aa0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
15ab0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15ac0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
15ad0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
15ae0 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
15af0 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
15b00 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
15b10 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
15b20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
15b30 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
15b40 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15b50 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
15b60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15b70 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15b80 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
15b90 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15ba0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15bc0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
15bd0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15be0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15bf0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15c00 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
15c10 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15c20 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
15c30 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
15c40 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
15c50 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
15c60 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
15c70 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
15ca0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15cb0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
15cc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15cd0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
15ce0 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
15cf0 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
15d00 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
15d10 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
15d20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15d30 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15d40 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
15d50 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
15d60 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
15d70 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
15d80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
15d90 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
15da0 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
15db0 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
15dc0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
15dd0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
15de0 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
15df0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
15e00 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
15e10 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
15e20 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
15e30 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
15e40 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
15e50 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
15e60 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
15e70 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
15e80 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
15e90 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
15ea0 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
15eb0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
15ec0 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
15ed0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
15ee0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15ef0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15f00 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15f10 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
15f20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
15f30 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
15f40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15f50 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
15f60 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
15f70 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15f80 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15f90 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15fb0 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15fc0 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15fd0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15fe0 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15ff0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
16000 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
16010 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
16020 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
16030 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
16040 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
16050 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
16060 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
16070 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
16080 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
16090 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
160a0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
160b0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
160c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
160d0 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
160e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
160f0 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
16100 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
16110 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
16120 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16130 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16140 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
16150 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
16160 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16170 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
16180 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
16190 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
161a0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
161b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
161c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
161d0 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
161e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
161f0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16200 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
16210 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16220 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
16230 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
16240 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
16250 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
16260 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
16270 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
16280 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
16290 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
162a0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
162b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
162c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
162d0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
162e0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
162f0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
16300 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
16310 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
16320 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
16330 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
16340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
16350 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
16360 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
16370 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
16380 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
16390 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
163a0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
163b0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
163c0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
163d0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
163e0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
163f0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
16400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16410 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
16420 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
16430 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
16440 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
16450 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
16460 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
16470 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
16480 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
16490 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
164a0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
164b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
164c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
164d0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
164e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
164f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
16500 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16510 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16520 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
16530 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16540 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
16550 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16560 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16570 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
16580 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
16590 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
165a0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
165b0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
165c0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
165d0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
165e0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
165f0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
16600 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
16610 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
16620 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
16630 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
16640 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
16650 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
16660 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
16670 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
16680 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
16690 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
166a0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
166b0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
166c0 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
166d0 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
166e0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
166f0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
16700 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
16710 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
16720 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
16730 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
16740 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
16750 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
16760 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
16770 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
16780 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
16790 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
167a0 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
167b0 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
167c0 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
167d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
167e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
167f0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
16800 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16810 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
16820 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16830 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
16840 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
16850 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
16860 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
16870 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
16880 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
16890 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
168a0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
168b0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
168c0 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
168d0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
168e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
168f0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
16900 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16910 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
16920 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
16930 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
16940 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
16950 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
16960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
16970 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
16980 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
16990 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
169a0 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
169b0 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
169c0 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
169d0 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
169e0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
169f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
16a00 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
16a10 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
16a20 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
16a30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16a40 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
16a50 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
16a60 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
16a70 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
16a80 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
16a90 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
16aa0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
16ab0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
16ac0 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
16ad0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
16ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
16af0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16b00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
16b10 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
16b20 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
16b30 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
16b40 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
16b50 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
16b60 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
16b70 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
16b80 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16b90 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
16ba0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16bb0 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
16bc0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
16bd0 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
16be0 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
16bf0 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
16c00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16c10 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
16c20 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
16c30 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
16c40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16c50 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
16c60 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
16c70 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
16c80 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
16c90 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
16ca0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
16cb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16cc0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
16cd0 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
16ce0 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
16cf0 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
16d00 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
16d10 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
16d20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16d30 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16d40 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
16d50 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16d60 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
16d70 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16d80 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
16d90 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
16da0 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
16db0 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
16dc0 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
16dd0 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
16de0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16df0 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
16e00 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
16e10 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16e20 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
16e30 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
16e40 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
16e50 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
16e60 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
16e70 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
16e80 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
16e90 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
16ea0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
16eb0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
16ec0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
16ed0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
16ee0 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
16ef0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16f00 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
16f10 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
16f20 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
16f30 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
16f40 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
16f50 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
16f60 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
16f70 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16f80 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16f90 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16fa0 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16fb0 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16fc0 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16fd0 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16fe0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16ff0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
17000 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
17010 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
17020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17030 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17040 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
17050 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17060 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
17070 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17080 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17090 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
170a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
170b0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
170c0 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
170d0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
170e0 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
170f0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
17100 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
17110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17120 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
17130 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
17140 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
17150 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
17160 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
17170 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
17180 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
17190 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
171a0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
171b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
171c0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
171d0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
171f0 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
17200 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17210 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17220 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
17230 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
17240 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
17250 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
17260 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
17270 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
17280 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
17290 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
172a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
172b0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
172c0 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
172d0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
172e0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
172f0 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
17300 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
17310 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
17320 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
17330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17340 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
17350 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
17360 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
17370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
17380 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
17390 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
173a0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
173b0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
173c0 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
173d0 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
173e0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
173f0 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
17400 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
17410 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
17420 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
17430 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
17440 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
17450 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
17460 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
17470 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
17480 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
17490 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
174a0 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
174b0 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
174c0 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
174d0 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
174e0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
174f0 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
17500 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
17510 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
17520 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
17530 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
17540 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
17550 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
17560 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
17570 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
17580 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17590 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
175a0 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
175b0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
175c0 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
175d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
175e0 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
175f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17600 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17610 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
17620 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
17630 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
17640 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
17650 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
17660 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
17670 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
17680 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
17690 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
176a0 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
176b0 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
176c0 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
176d0 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
176e0 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
176f0 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
17700 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
17710 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
17720 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
17730 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
17740 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
17750 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
17760 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
17770 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
17780 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
17790 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
177a0 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
177b0 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
177c0 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
177d0 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
177e0 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
177f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
17800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
17810 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
17820 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
17830 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
17840 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
17850 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17860 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
17870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17880 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
17890 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
178a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
178b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
178c0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
178d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
178e0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
178f0 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
17900 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17910 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
17920 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
17930 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
17940 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17950 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
17960 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
17970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
17980 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
17990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
179a0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
179b0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
179c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
179d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
179e0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
179f0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
17a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a10 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
17a20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
17a30 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
17a40 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
17a50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17a60 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
17a70 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
17a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17a90 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
17aa0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
17ab0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
17ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ad0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
17ae0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
17af0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
17b00 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
17b10 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
17b20 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
17b30 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
17b40 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
17b50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b60 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
17b70 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
17b80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17b90 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
17ba0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
17bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17bc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17bd0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
17be0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
17bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17c00 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
17c10 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
17c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17c30 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
17c40 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17c60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17c70 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17c80 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17c90 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17cb0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17cc0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17cd0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17cf0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17d00 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
17d10 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17d20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
17d30 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
17d40 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d60 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17d70 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17d80 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17d90 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17db0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17dc0 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17dd0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17df0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
17e00 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
17e10 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
17e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
17e30 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
17e40 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17e50 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17e70 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17e80 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17e90 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
17ea0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17eb0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20  _SMALL_MALLOC   
17ec0 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c       27  /* bool
17ed0 65 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ean */../*.** CA
17ee0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
17ef0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
17f00 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
17f10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
17f20 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
17f30 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
17f40 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
17f50 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
17f60 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
17f70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17f80 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
17f90 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17fa0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
17fb0 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
17fc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
17fd0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
17fe0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
17ff0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
18000 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
18010 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
18020 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
18030 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
18040 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
18050 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
18060 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
18070 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
18080 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
18090 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
180a0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
180b0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
180c0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
180d0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
180e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
180f0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
18100 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
18110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18120 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
18130 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
18140 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18150 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
18160 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18170 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
18180 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
18190 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
181a0 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
181b0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
181c0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
181d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
181e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
181f0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
18200 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18210 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
18220 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
18230 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
18240 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
18250 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
18260 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
18270 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
18280 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18290 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
182a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
182b0 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
182c0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
182d0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
182e0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
182f0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
18300 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
18310 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
18320 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
18330 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
18340 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
18350 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
18360 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
18370 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18380 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
18390 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
183a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
183b0 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
183c0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
183d0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
183e0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
183f0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
18400 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
18410 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
18420 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
18430 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
18440 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
18450 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
18460 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
18470 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
18480 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
18490 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
184a0 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
184b0 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
184c0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
184d0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
184e0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
184f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18500 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
18510 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
18520 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
18530 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
18540 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
18550 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
18560 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
18570 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
18580 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
18590 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
185a0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
185b0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
185c0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
185d0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
185e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
185f0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
18600 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
18610 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
18620 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
18630 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
18640 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
18650 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
18660 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
18670 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
18680 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
18690 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
186a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
186b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
186c0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
186d0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
186e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
186f0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18700 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
18710 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
18720 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
18730 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
18740 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18750 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
18760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18770 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
18780 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
18790 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
187a0 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
187b0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
187c0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
187d0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
187e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
187f0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
18800 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18810 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18820 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
18830 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18840 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18850 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18860 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
18870 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
18880 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18890 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
188a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
188b0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
188c0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
188d0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
188e0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
188f0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18900 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
18910 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18920 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
18930 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
18940 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
18950 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
18960 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
18970 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
18980 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
18990 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
189a0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
189b0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
189c0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
189d0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
189e0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
189f0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
18a00 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18a10 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
18a20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
18a30 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
18a40 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
18a50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18a60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18a70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18a80 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18a90 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18aa0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
18ab0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
18ac0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18ad0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18ae0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18af0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18b00 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18b10 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18b20 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
18b30 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18b40 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18b50 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18b60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18b70 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
18b80 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
18b90 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18ba0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18bb0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77  r disable the tw
18bc0 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65  o-argument.** ve
18bd0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74  rsion of the [ft
18be0 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20  s3_tokenizer()] 
18bf0 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69  function which i
18c00 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
18c10 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78   [FTS3] full-tex
18c20 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20  t search engine 
18c30 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68  extension..** Th
18c40 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18c50 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18c60 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18c70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18c80 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18c90 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18ca0 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18cb0 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76  () or.** positiv
18cc0 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33  e to enable fts3
18cd0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20  _tokenizer() or 
18ce0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
18cf0 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  e the setting.**
18d00 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
18d10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18d20 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18d30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
18d40 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18d50 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18d60 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18d70 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  er fts3_tokenize
18d80 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  r is disabled or
18d90 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
18da0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18db0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18dc0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
18dd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18de0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18df0 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
18e00 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18e10 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18e20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18e30 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
18e40 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
18e50 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18e60 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18e70 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18e80 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
18e90 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18ea0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
18eb0 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
18ec0 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
18ed0 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
18ee0 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
18ef0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
18f00 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
18f10 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18f20 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
18f30 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
18f40 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18f50 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
18f60 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
18f70 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
18f80 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18f90 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18fa0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
18fb0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18fc0 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
18fd0 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
18fe0 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
18ff0 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
19000 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19010 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
19020 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
19030 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
19040 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
19050 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
19060 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
19070 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
19080 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
19090 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
190a0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
190b0 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
190c0 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
190d0 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
190e0 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
190f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
19100 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19110 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19120 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
19130 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
19140 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19150 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
19160 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
19170 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
19180 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
19190 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
191a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
191b0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
191c0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
191d0 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
191e0 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
191f0 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
19200 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19210 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
19220 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19230 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
19240 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20  NDBNAME</dt>.** 
19250 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
19260 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61  n is used to cha
19270 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nge the name of 
19280 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62  the "main" datab
19290 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20  ase.** schema.  
192a0 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65  ^The sole argume
192b0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
192c0 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54  to a constant UT
192d0 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69  F8 string.** whi
192e0 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ch will become t
192f0 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61  he new schema na
19300 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  me in place of "
19310 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a  main".  ^SQLite.
19320 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65  ** does not make
19330 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e   a copy of the n
19340 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e  ew main schema n
19350 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74  ame string, so t
19360 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
19370 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
19380 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  at the argument 
19390 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73  passed into this
193a0 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e   DBCONFIG option
193b0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a   is unchanged.**
193c0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
193d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
193e0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
193f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19400 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19410 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
19420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73  </dt>.** <dd> Us
19430 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61  ually, when a da
19440 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f  tabase in wal mo
19450 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  de is closed or 
19460 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20  detached from a 
19470 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
19480 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63  dle, SQLite chec
19490 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20  ks if this will 
194a0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20  mean that there 
194b0 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63  are now no .** c
194c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c  onnections at al
194d0 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  l to the databas
194e0 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72  e. If so, it per
194f0 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69  forms a checkpoi
19500 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  nt .** operation
19510 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20   before closing 
19520 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
19530 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20  This option may 
19540 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76  be used to.** ov
19550 65 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61  erride this beha
19560 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74  viour. The first
19570 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
19580 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74  d to this operat
19590 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ion.** is an int
195a0 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20  eger - non-zero 
195b0 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b  to disable check
195c0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c  points-on-close,
195d0 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a   or zero (the.**
195e0 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61   default) to ena
195f0 62 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65  ble them. The se
19600 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19610 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19620 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74  n integer.** int
19630 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74  o which is writt
19640 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19650 69 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68  icate whether ch
19660 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
19670 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  se.** have been 
19680 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20  disabled - 0 if 
19690 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73  they are not dis
196a0 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79  abled, 1 if they
196b0 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   are..** </dd>.*
196c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
196d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
196e0 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  QPSG</dt>.** <dd
196f0 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42  >^(The SQLITE_DB
19700 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
19710 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61  SG option activa
19720 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74  tes or deactivat
19730 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79  es.** the [query
19740 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69   planner stabili
19750 74 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51  ty guarantee] (Q
19760 50 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20  PSG).  When the 
19770 51 50 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a  QPSG is active,.
19780 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ** a single SQL 
19790 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20  query statement 
197a0 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20  will always use 
197b0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
197c0 68 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  hm regardless.**
197d0 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62   of values of [b
197e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d  ound parameters]
197f0 2e 29 5e 20 54 68 65 20 51 50 53 47 20 64 69 73  .)^ The QPSG dis
19800 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79  ables some query
19810 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a   optimizations.*
19820 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74  * that look at t
19830 68 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75  he values of bou
19840 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77  nd parameters, w
19850 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f  hich can make so
19860 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c  me queries.** sl
19870 6f 77 65 72 2e 20 20 42 75 74 20 74 68 65 20 51  ower.  But the Q
19880 50 53 47 20 68 61 73 20 74 68 65 20 61 64 76 61  PSG has the adva
19890 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72  ntage of more pr
198a0 65 64 69 63 74 61 62 6c 65 20 62 65 68 61 76 69  edictable behavi
198b0 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65  or.  With.** the
198c0 20 51 50 53 47 20 61 63 74 69 76 65 2c 20 53 51   QPSG active, SQ
198d0 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
198e0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 71 75   use the same qu
198f0 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20  ery plan in the 
19900 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20  field as.** was 
19910 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
19920 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a  ing in the lab..
19930 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19940 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
19950 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19960 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
19970 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
19980 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
19990 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
199a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
199b0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
199c0 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
199d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
199e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
199f0 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
19a00 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
19a10 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19a20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19a30 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
19a40 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
19a50 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19a60 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19a70 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
19a80 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
19a90 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19aa0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19ab0 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
19ac0 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
19ad0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19ae0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19af0 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
19b00 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
19b10 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19b30 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
19b40 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37  G           1007
19b50 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19b70 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
19b80 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
19b90 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
19ba0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19bb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19bc0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
19bd0 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
19be0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
19bf0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
19c00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
19c10 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
19c20 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
19c30 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
19c40 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
19c50 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
19c60 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
19c70 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
19c80 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
19c90 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
19ca0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
19cb0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
19cc0 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
19cd0 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
19ce0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19cf0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
19d00 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
19d10 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
19d20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
19d30 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
19d40 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
19d50 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
19d60 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
19d70 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
19d80 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
19d90 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
19da0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
19db0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
19dc0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
19dd0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
19de0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
19df0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
19e00 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
19e10 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
19e20 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
19e30 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
19e40 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
19e50 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
19e60 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
19e70 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
19e80 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
19e90 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
19ea0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19eb0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
19ec0 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
19ed0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19ee0 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
19ef0 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
19f00 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
19f10 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
19f20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
19f30 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
19f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
19f50 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
19f60 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19f70 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
19f80 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
19f90 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19fa0 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19fb0 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
19fc0 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
19fd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19fe0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
19ff0 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
1a000 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
1a010 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
1a020 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
1a030 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
1a040 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
1a050 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
1a060 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
1a070 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
1a080 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1a090 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1a0a0 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
1a0b0 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
1a0c0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1a0d0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
1a0e0 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
1a0f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1a100 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
1a110 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
1a120 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
1a130 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
1a140 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
1a150 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
1a160 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
1a170 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
1a180 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
1a190 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1a1a0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1a1b0 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
1a1c0 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
1a1d0 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
1a1e0 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
1a1f0 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
1a200 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
1a210 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
1a220 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
1a230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
1a240 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
1a250 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
1a260 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
1a270 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
1a280 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
1a290 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
1a2a0 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
1a2b0 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
1a2c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a2d0 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
1a2e0 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
1a2f0 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
1a300 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
1a310 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
1a320 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
1a330 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1a340 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
1a350 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
1a360 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
1a370 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
1a380 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
1a390 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
1a3a0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1a3b0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
1a3c0 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
1a3d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
1a3e0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
1a3f0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
1a400 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
1a410 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1a420 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1a430 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1a440 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1a450 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1a460 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1a470 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1a480 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1a490 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1a4a0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1a4b0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1a4c0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1a4d0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1a4e0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1a4f0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1a500 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1a510 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1a520 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1a530 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1a540 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1a550 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1a560 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1a570 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1a580 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1a590 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1a5a0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1a5b0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1a5c0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1a5d0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1a5e0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1a5f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1a600 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1a610 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1a620 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1a630 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a640 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1a650 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1a660 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1a670 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1a680 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1a690 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1a6a0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1a6b0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1a6c0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1a6d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1a6e0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1a6f0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1a700 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1a710 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1a720 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1a730 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1a740 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1a750 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1a760 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1a770 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1a780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1a790 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1a7a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a7b0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1a7c0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1a7d0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1a7e0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a7f0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1a800 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a810 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1a820 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a830 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1a840 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1a850 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1a860 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1a870 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1a880 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
1a890 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1a8a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1a8b0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
1a8c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a8d0 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
1a8e0 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
1a8f0 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
1a900 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
1a910 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
1a920 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1a930 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
1a940 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
1a950 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
1a960 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a970 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
1a980 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1a990 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
1a9a0 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
1a9b0 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
1a9c0 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
1a9d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
1a9e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a9f0 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
1aa00 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
1aa10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
1aa20 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
1aa30 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1aa40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1aa50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1aa60 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1aa70 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1aa80 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1aa90 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1aaa0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1aab0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1aac0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1aad0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1aae0 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1aaf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ab00 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1ab10 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1ab20 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1ab30 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1ab40 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1ab50 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1ab60 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1ab70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1ab80 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1ab90 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1aba0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1abb0 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1abc0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1abd0 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1abe0 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1abf0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1ac00 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1ac10 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1ac20 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1ac30 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1ac40 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1ac50 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1ac60 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1ac70 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1ac80 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1ac90 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1aca0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1acb0 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1acc0 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1acd0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ace0 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1acf0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ad00 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1ad10 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1ad20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1ad30 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1ad40 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1ad50 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1ad60 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1ad70 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1ad80 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1ad90 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1ada0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1adb0 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1adc0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1add0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1ade0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1adf0 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1ae00 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1ae10 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1ae20 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1ae30 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1ae40 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1ae50 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1ae60 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1ae70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1ae80 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1ae90 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1aea0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1aeb0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1aec0 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1aed0 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1aee0 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1aef0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1af00 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1af10 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1af20 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1af30 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1af40 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1af50 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1af60 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1af70 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1af80 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1af90 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1afa0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1afb0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1afc0 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1afd0 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1afe0 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1aff0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1b000 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1b010 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1b020 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1b030 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1b040 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1b050 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1b060 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1b070 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1b080 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1b090 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b0a0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1b0b0 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1b0c0 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1b0d0 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1b0e0 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1b0f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1b100 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1b110 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1b120 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1b130 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1b140 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1b150 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1b160 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1b170 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1b180 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1b190 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1b1a0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1b1b0 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1b1c0 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1b1d0 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1b1e0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1b1f0 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1b200 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1b210 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1b220 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1b230 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b240 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1b250 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1b260 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1b270 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1b280 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b290 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b2a0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1b2b0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1b2c0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1b2d0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b2e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1b2f0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1b300 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1b310 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1b320 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b330 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b340 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1b350 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1b360 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1b370 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1b380 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1b390 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1b3a0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1b3b0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1b3c0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b3d0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1b3e0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1b3f0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1b400 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1b410 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1b420 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1b430 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1b440 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1b450 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1b460 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1b470 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1b480 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1b490 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1b4a0 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1b4b0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1b4c0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1b4d0 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1b4e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1b4f0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1b500 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1b510 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1b520 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1b530 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1b540 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1b550 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1b560 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1b570 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1b580 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b590 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1b5a0 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1b5b0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1b5c0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1b5d0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1b5e0 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1b5f0 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1b600 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1b610 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1b620 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1b630 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1b640 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1b650 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1b660 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1b670 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b680 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1b690 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
1b6a0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1b6b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b6c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1b6d0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1b6e0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1b6f0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1b700 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b710 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b720 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1b730 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1b740 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1b750 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1b760 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1b770 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1b780 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b790 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1b7a0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1b7b0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b7c0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1b7d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1b7e0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1b7f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b800 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1b810 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1b820 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b830 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1b840 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1b850 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1b860 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1b870 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1b880 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1b890 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1b8a0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1b8b0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1b8c0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1b8d0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1b8e0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1b8f0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1b900 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1b910 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1b920 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1b930 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1b940 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1b950 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1b960 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1b970 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1b980 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1b990 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1b9a0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1b9b0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1b9c0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1b9d0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1b9e0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1b9f0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1ba00 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1ba10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1ba20 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1ba30 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1ba40 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1ba50 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1ba60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1ba70 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1ba80 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1ba90 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1baa0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1bab0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1bac0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1bad0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1bae0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1baf0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1bb00 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1bb10 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1bb20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1bb30 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1bb40 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1bb50 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1bb60 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1bb70 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1bb80 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1bb90 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1bba0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1bbb0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1bbc0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1bbd0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1bbe0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1bbf0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1bc00 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1bc10 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1bc20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1bc30 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1bc40 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1bc50 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1bc60 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1bc70 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1bc80 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1bc90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1bca0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1bcb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1bcc0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1bcd0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1bce0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bcf0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1bd00 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1bd10 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1bd20 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1bd30 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1bd40 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1bd50 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1bd60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1bd70 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1bd80 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1bd90 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1bda0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1bdb0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1bdc0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1bdd0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1bde0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1bdf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1be00 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1be10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1be20 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1be30 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1be40 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1be50 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1be60 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1be70 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1be80 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1be90 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1bea0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1beb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bec0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1bed0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1bee0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1bef0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1bf00 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1bf10 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1bf20 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1bf30 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1bf40 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1bf50 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1bf60 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1bf70 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1bf80 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1bf90 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1bfa0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1bfb0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1bfc0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1bfd0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1bfe0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1bff0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1c000 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1c010 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1c020 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c030 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1c040 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1c050 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1c060 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1c070 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1c080 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1c090 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1c0a0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1c0b0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1c0c0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1c0d0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1c0e0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1c0f0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1c100 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1c110 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1c120 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1c130 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1c140 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1c150 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1c160 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1c170 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1c180 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1c190 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1c1a0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1c1b0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1c1c0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1c1d0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1c1e0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1c1f0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1c200 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1c210 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1c220 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1c230 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1c240 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c250 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1c260 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1c270 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1c280 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1c290 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1c2a0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1c2b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1c2c0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1c2d0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1c2e0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1c2f0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1c300 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1c310 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1c320 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1c330 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1c340 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1c350 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1c360 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1c370 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1c380 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c390 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1c3a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1c3b0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1c3c0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1c3d0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c3e0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1c3f0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1c400 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1c410 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1c420 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1c430 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1c440 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1c450 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1c460 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1c470 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1c480 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1c490 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1c4a0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1c4b0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1c4c0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1c4d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1c4e0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1c4f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1c500 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c510 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c520 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1c530 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1c540 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1c550 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1c560 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
1c570 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c580 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1c590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c5a0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1c5b0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1c5c0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1c5d0 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1c5e0 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1c5f0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1c600 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1c610 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c620 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1c630 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1c640 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1c650 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1c660 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1c670 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1c680 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1c690 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1c6a0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1c6b0 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1c6c0 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1c6d0 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1c6e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c6f0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1c700 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1c710 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1c720 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1c730 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1c740 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1c750 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1c760 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1c770 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c780 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1c790 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1c7a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1c7b0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1c7c0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1c7d0 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1c7e0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1c7f0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1c800 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1c810 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1c820 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1c830 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1c840 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1c850 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1c860 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1c870 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1c880 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1c890 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1c8a0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1c8b0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1c8c0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1c8d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1c8e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c8f0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1c900 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1c910 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c920 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1c930 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1c940 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1c950 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1c960 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1c970 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1c980 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1c990 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1c9a0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1c9b0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1c9c0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1c9d0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1c9e0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1c9f0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1ca00 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1ca10 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1ca20 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1ca30 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1ca40 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1ca50 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1ca60 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1ca70 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1ca80 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1ca90 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1caa0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1cab0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1cac0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1cad0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1cae0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1caf0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1cb00 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1cb10 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1cb20 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1cb30 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1cb40 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1cb50 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1cb60 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1cb70 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1cb80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1cb90 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1cba0 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1cbb0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1cbc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1cbd0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1cbe0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1cbf0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1cc00 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1cc10 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1cc20 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1cc30 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1cc40 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1cc50 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1cc60 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1cc70 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1cc80 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1cc90 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1cca0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1ccb0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1ccc0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1ccd0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1cce0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1ccf0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1cd00 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1cd10 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1cd20 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1cd30 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1cd40 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1cd50 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1cd60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1cd70 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1cd80 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1cd90 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1cda0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1cdb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1cdc0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1cdd0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1cde0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1cdf0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1ce00 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1ce10 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1ce20 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1ce30 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1ce40 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1ce50 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1ce60 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1ce70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1ce80 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1ce90 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1cea0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1ceb0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1cec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1ced0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1cee0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1cef0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1cf00 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1cf10 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1cf20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1cf30 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1cf40 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1cf50 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1cf60 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1cf70 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1cf80 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1cf90 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1cfa0 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1cfb0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1cfc0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1cfd0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1cfe0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1cff0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1d000 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1d010 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1d020 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1d030 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1d040 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1d050 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1d060 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1d070 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1d080 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1d090 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1d0a0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1d0b0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1d0c0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1d0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1d0e0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1d0f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1d100 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1d110 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1d120 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d130 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a  r(sqlite3*,int(*
1d140 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69  )(void*,int),voi
1d150 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d160 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1d170 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1d180 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1d190 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1d1a0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1d1b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1d1c0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1d1d0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1d1e0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1d1f0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1d200 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1d210 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1d220 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1d230 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1d240 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1d250 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1d260 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1d270 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1d280 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1d290 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d2a0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1d2b0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1d2c0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1d2d0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1d2e0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1d2f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1d300 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1d310 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1d320 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1d330 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1d340 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1d350 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1d360 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1d370 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1d380 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1d390 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1d3a0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1d3b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d3c0 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1d3d0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1d3e0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1d3f0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1d400 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1d410 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1d420 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1d430 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1d440 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1d450 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1d460 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1d470 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1d480 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1d490 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1d4a0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1d4b0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1d4c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d4d0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1d4e0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1d4f0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1d500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1d510 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1d520 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1d530 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1d540 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1d550 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1d560 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1d570 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1d580 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1d590 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1d5a0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1d5b0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1d5c0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1d5d0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1d5e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d5f0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1d600 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d610 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1d620 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1d630 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1d640 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1d650 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1d660 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1d670 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1d680 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1d690 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1d6a0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1d6b0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1d6c0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1d6d0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1d6e0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1d6f0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1d700 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1d710 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1d720 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1d730 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1d740 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1d750 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1d760 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1d770 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1d780 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1d790 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1d7a0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1d7b0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1d7c0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1d7d0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1d7e0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1d7f0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1d800 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1d810 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1d820 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1d830 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1d840 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1d850 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1d860 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1d870 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1d880 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1d890 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1d8a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1d8b0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1d8c0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1d8d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1d8e0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1d8f0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1d900 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1d910 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1d920 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1d930 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1d940 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1d950 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1d960 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1d970 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1d980 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1d990 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1d9a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1d9b0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1d9c0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1d9d0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1d9e0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1d9f0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1da00 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1da10 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1da20 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1da30 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1da40 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1da50 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1da60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1da70 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1da80 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1da90 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1daa0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1dab0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1dac0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1dad0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1dae0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1daf0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1db00 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1db10 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1db20 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1db30 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1db40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1db50 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1db60 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1db70 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1db80 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1db90 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1dba0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1dbb0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1dbc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1dbd0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1dbe0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dbf0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1dc00 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1dc10 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1dc20 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1dc30 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1dc40 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1dc50 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1dc60 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1dc70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1dc80 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1dc90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dca0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1dcb0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1dcc0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1dcd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1dce0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1dcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1dd00 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1dd10 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1dd20 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1dd30 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1dd40 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1dd50 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1dd60 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1dd70 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1dd80 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1dd90 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1dda0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1ddb0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1ddc0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1ddd0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1dde0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1ddf0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1de00 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1de10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1de20 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1de30 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1de40 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1de50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1de60 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1de70 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1de80 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1de90 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1dea0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1deb0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1dec0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1ded0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1dee0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1def0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1df00 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1df10 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1df20 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1df30 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1df40 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1df50 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1df60 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1df70 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1df80 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1df90 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1dfa0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1dfb0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1dfc0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1dfd0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1dfe0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1dff0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e000 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1e010 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1e020 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1e030 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1e040 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1e050 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1e060 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1e070 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1e080 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1e090 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1e0a0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1e0b0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1e0c0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1e0d0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1e0e0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1e0f0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1e100 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1e110 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1e120 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1e130 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1e140 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1e150 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1e160 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e170 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1e180 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1e190 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e1a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1e1b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1e1c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1e1d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1e1e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1e1f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1e200 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1e210 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1e220 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1e230 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1e240 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1e250 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1e260 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1e270 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1e280 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1e290 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1e2a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1e2b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1e2c0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1e2d0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1e2e0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1e2f0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1e300 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1e310 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e320 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1e330 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1e340 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1e350 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1e360 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1e370 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1e380 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1e390 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1e3a0 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1e3b0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1e3c0 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1e3d0 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1e3e0 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1e3f0 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1e400 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1e410 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1e420 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1e430 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1e440 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1e450 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1e460 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1e470 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1e480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e490 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1e4a0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1e4b0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1e4c0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1e4d0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1e4e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1e4f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e500 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1e510 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1e520 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1e530 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1e540 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1e550 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1e560 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1e570 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1e580 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1e590 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1e5a0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1e5b0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1e5c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1e5d0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1e5e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1e5f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1e600 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1e610 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1e620 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1e630 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1e640 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1e650 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1e660 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1e670 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1e680 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1e690 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1e6a0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1e6b0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1e6c0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1e6d0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1e6e0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1e6f0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1e700 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1e710 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1e720 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1e730 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1e740 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1e750 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1e760 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1e770 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1e780 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1e790 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1e7a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1e7b0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1e7c0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1e7d0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1e7e0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1e7f0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1e800 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1e810 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1e820 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1e830 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1e840 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1e850 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1e860 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1e870 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1e880 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1e890 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1e8a0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1e8b0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1e8c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1e8d0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1e8e0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1e8f0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1e900 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1e910 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1e920 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1e930 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1e940 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1e950 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1e960 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1e970 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1e980 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1e990 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1e9a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1e9b0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1e9c0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1e9d0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1e9e0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1e9f0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1ea00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1ea10 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1ea20 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1ea30 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1ea40 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1ea50 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1ea60 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1ea70 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1ea80 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1ea90 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1eaa0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1eab0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1eac0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1ead0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1eae0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1eaf0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1eb00 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1eb10 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1eb20 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1eb30 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1eb40 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1eb50 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1eb60 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1eb70 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1eb80 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1eb90 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1eba0 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1ebb0 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1ebc0 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1ebd0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1ebe0 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1ebf0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1ec00 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1ec10 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1ec20 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1ec30 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1ec40 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1ec50 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1ec60 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1ec70 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1ec80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1ec90 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1eca0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1ecb0 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1ecc0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1ecd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ece0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1ecf0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1ed00 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1ed10 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ed20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1ed30 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1ed40 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1ed50 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1ed60 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ed70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ed80 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1ed90 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1eda0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1edb0 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1edc0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1edd0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1ede0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1edf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1ee00 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1ee10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ee20 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1ee30 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1ee40 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1ee50 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1ee60 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1ee70 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1ee80 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1ee90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1eea0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1eeb0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1eec0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1eed0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1eee0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1eef0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ef00 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1ef10 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1ef20 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1ef30 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1ef40 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1ef50 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1ef60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ef70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1ef80 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1ef90 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1efa0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1efb0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1efc0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1efd0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1efe0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1eff0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1f000 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1f010 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1f020 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1f030 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1f040 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1f050 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1f060 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1f070 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f080 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1f090 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1f0a0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1f0b0 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1f0c0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1f0d0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1f0e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f0f0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1f100 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1f110 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1f120 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1f130 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1f140 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1f150 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1f160 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1f170 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1f180 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f190 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1f1a0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1f1b0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1f1c0 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1f1d0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1f1e0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1f1f0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1f200 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1f210 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1f220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1f230 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1f240 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1f250 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1f260 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1f270 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1f280 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1f290 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1f2a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1f2b0 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1f2c0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1f2d0 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1f2e0 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1f2f0 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1f300 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1f310 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1f320 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1f330 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1f340 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1f350 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1f360 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1f370 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1f380 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1f390 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1f3a0 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1f3b0 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1f3c0 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1f3d0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1f3e0 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1f3f0 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1f400 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1f410 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1f420 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1f430 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1f440 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1f450 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1f460 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1f470 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1f480 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1f490 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1f4a0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1f4b0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1f4c0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1f4d0 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1f4e0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1f4f0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1f500 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1f510 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1f520 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f530 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1f540 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1f550 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1f560 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1f570 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1f580 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1f590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f5a0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1f5b0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1f5c0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1f5d0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1f5e0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1f5f0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1f600 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1f610 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1f620 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1f630 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1f640 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1f650 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1f660 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1f670 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1f680 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1f690 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1f6a0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1f6b0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1f6c0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1f6d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f6e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1f6f0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1f700 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1f710 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1f720 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1f730 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1f740 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1f750 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1f760 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1f770 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1f780 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1f790 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1f7a0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1f7b0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1f7c0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1f7d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f7e0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1f7f0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1f800 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1f810 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1f820 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1f830 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1f840 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1f850 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1f860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1f870 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1f880 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1f890 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1f8a0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1f8b0 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1f8c0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1f8d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1f8e0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1f8f0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1f900 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1f910 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1f920 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f930 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1f940 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1f950 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1f960 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1f970 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1f980 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1f990 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1f9a0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1f9b0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1f9c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1f9d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1f9e0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1f9f0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1fa00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1fa10 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1fa20 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1fa30 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1fa40 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1fa50 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1fa60 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1fa70 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1fa80 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1fa90 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1faa0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1fab0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1fac0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1fad0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1fae0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1faf0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1fb00 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1fb10 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1fb20 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1fb30 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1fb40 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1fb50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1fb60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fb70 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1fb80 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1fb90 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1fba0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1fbb0 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1fbc0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1fbd0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1fbe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1fbf0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fc00 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1fc10 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1fc20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1fc30 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1fc40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1fc50 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1fc60 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1fc70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fc80 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1fc90 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1fca0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1fcb0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1fcc0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1fcd0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1fce0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1fcf0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1fd00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1fd10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1fd20 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1fd30 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1fd40 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1fd50 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1fd60 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1fd70 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1fd80 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1fd90 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1fda0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1fdb0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1fdc0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1fdd0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1fde0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1fdf0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1fe00 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1fe10 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1fe20 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1fe30 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1fe40 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1fe50 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1fe60 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1fe70 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1fe80 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1fe90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1fea0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1feb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1fec0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1fed0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1fee0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1fef0 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1ff00 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1ff10 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1ff20 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1ff30 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1ff40 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1ff50 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1ff60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1ff70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1ff80 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1ff90 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1ffa0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1ffb0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ffc0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1ffd0 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1ffe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1fff0 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
20000 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
20010 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20020 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
20030 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20040 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
20050 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
20060 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
20070 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
20080 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
20090 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
200a0 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
200b0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
200c0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
200d0 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
200e0 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
200f0 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
20100 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
20110 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
20120 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
20130 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
20140 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
20150 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
20160 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
20170 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
20180 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20190 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
201a0 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
201b0 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
201c0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
201d0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
201e0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
201f0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
20200 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
20210 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
20220 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
20230 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
20240 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
20250 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
20260 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
20270 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
20280 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
20290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
202a0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
202b0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
202c0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
202d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
202e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
202f0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
20300 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
20310 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
20320 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
20330 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
20340 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
20350 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
20360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20370 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
20380 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
20390 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
203a0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
203b0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
203c0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
203d0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
203e0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
203f0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
20400 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
20410 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
20420 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
20430 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
20440 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
20450 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
20460 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
20470 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
20480 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
20490 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
204a0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
204b0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
204c0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
204d0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
204e0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
204f0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
20500 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
20510 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
20520 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
20530 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
20540 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
20550 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
20560 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
20570 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
20580 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
20590 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
205a0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
205b0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
205c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
205d0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
205e0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
205f0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
20600 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
20610 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
20620 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20630 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20640 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
20650 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
20660 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
20670 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
20680 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
20690 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
206a0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
206b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
206c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
206d0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
206e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
206f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
20700 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
20710 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
20720 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
20730 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
20740 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
20750 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
20760 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
20770 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
20780 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
20790 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
207a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
207b0 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
207c0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
207d0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
207e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
207f0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
20800 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
20810 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
20820 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
20830 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
20840 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
20850 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
20860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20870 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
20880 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
20890 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
208a0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
208b0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
208c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
208d0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
208e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
208f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20900 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20910 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20920 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
20930 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
20940 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
20950 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
20960 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
20970 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20980 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
20990 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
209a0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
209b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
209c0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
209d0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
209e0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
209f0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
20a00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
20a10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20a20 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
20a30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20a40 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
20a50 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
20a60 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
20a70 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
20a80 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
20a90 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
20aa0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
20ab0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
20ac0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
20ad0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
20ae0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
20af0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20b00 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
20b10 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
20b20 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
20b30 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
20b40 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
20b50 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20b60 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
20b70 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
20b80 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
20b90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20ba0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
20bb0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
20bc0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
20bd0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20be0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
20bf0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20c00 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
20c10 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
20c20 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20c30 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
20c40 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
20c50 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
20c60 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
20c70 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
20c80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
20c90 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
20ca0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20cb0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20cc0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20cd0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20ce0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20cf0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20d00 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20d10 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
20d20 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20d30 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
20d40 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
20d50 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
20d60 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
20d70 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20d80 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20d90 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20da0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20db0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20dc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
20dd0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20de0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
20df0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
20e00 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
20e10 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
20e20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
20e30 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
20e40 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
20e50 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
20e60 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
20e70 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
20e80 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
20e90 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
20ea0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
20eb0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
20ec0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
20ed0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
20ee0 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
20ef0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
20f00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
20f10 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
20f20 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
20f30 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
20f40 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
20f50 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
20f60 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
20f70 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
20f80 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
20f90 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
20fa0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
20fb0 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
20fc0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
20fd0 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
20fe0 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
20ff0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
21000 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
21010 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
21020 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
21030 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
21040 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
21050 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
21060 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
21070 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
21080 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
21090 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
210a0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
210b0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
210c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
210d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68   KEYWORDS: {auth
210e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d  orizer callback}
210f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
21100 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
21110 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
21120 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
21130 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
21140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21150 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
21160 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
21170 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
21180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
21190 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
211a0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
211b0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
211c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
211d0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
211e0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
211f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
21200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21210 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
21220 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21230 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
21240 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61  re16_v2()],.** a
21250 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
21260 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41  are16_v3()].  ^A
21270 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
21280 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
21290 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
212a0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
212b0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
212c0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
212d0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
212e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
212f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21300 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
21310 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
21320 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
21330 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21340 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
21350 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
21360 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
21370 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
21380 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
21390 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
213a0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
213b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
213c0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
213d0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
213e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
213f0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
21400 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
21410 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
21420 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
21430 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
21440 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21450 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
21460 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
21470 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
21480 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
21490 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
214a0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
214b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
214c0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
214d0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
214e0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
214f0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
21500 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
21510 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
21520 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
21530 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21540 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
21550 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
21560 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
21570 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
21580 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21590 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
215a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
215b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
215c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
215d0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
215e0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
215f0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
21600 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21610 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
21620 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
21630 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
21640 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21650 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
21660 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
21680 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
21690 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
216a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
216b0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
216c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
216d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
216e0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
216f0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
21700 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
21710 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
21720 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
21730 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
21740 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
21750 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
21760 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
21770 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
21780 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20  are either NULL 
21790 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f  pointers or zero
217a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
217b0 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74  ngs.** that cont
217c0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64  ain additional d
217d0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
217e0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
217f0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70  thorized..** App
21800 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61  lications must a
21810 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65  lways be prepare
21820 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61  d to encounter a
21830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
21840 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74   any.** of the t
21850 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65  hird through the
21860 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
21870 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69  s of the authori
21880 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  zation callback.
21890 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
218a0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
218b0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
218c0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
218d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
218e0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
218f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
21900 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
21910 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
21920 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
21930 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
21940 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
21950 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
21960 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
21970 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
21980 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
21990 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
219a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
219b0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
219c0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
219d0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
219e0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
219f0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
21a00 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
21a10 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73  ^When a table is
21a20 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61   referenced by a
21a30 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f   [SELECT] but no
21a40 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61   column values a
21a50 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20  re.** extracted 
21a60 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20  from that table 
21a70 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20  (for example in 
21a80 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20  a query like.** 
21a90 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29  "SELECT count(*)
21aa0 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e   FROM tab") then
21ab0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41   the [SQLITE_REA
21ac0 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  D] authorizer ca
21ad0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76  llback.** is inv
21ae0 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68  oked once for th
21af0 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20  at table with a 
21b00 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74  column name that
21b10 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
21b20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
21b30 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21b40 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
21b50 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
21b60 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
21b70 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
21b80 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
21b90 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
21ba0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
21bb0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
21bc0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
21bd0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
21be0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
21bf0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
21c00 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
21c10 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
21c20 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21c30 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
21c40 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
21c50 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
21c60 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
21c70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21c80 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
21c90 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
21ca0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
21cb0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
21cc0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
21cd0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
21ce0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
21cf0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
21d00 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
21d10 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
21d20 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
21d30 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
21d40 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
21d50 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
21d60 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
21d70 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
21d80 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
21d90 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
21da0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
21db0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
21dc0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
21dd0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
21de0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
21df0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
21e00 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
21e10 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
21e20 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
21e30 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
21e40 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
21e50 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
21e60 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
21e70 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
21e80 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
21e90 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
21ea0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
21eb0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
21ec0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
21ed0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
21ee0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
21ef0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
21f00 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
21f10 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
21f20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
21f30 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
21f40 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
21f50 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
21f60 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
21f70 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
21f80 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
21f90 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
21fa0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
21fb0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
21fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
21fd0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
21fe0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
21ff0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22000 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
22010 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
22020 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
22030 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
22040 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
22050 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
22060 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
22070 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
22080 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
22090 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
220a0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
220b0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
220c0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
220d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
220e0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
220f0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
22100 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
22110 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
22120 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22130 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
22140 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
22150 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
22160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
22170 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
22180 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
22190 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
221a0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
221b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
221c0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
221d0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
221e0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
221f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
22200 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
22210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
22220 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
22230 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
22240 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
22250 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
22260 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
22270 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
22280 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
22290 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
222a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
222b0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
222c0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
222d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
222e0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
222f0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
22300 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
22310 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
22320 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
22330 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
22340 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
22350 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
22360 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22370 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
22380 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
22390 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
223a0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
223b0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
223c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
223d0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
223e0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
223f0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
22400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22410 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
22420 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
22430 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
22440 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
22450 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
22460 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
22470 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
22480 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
22490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
224a0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
224b0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
224c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
224d0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
224e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
224f0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
22500 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
22510 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
22520 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
22530 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
22540 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
22550 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
22560 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
22570 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
22580 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22590 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
225a0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
225b0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
225c0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
225d0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
225e0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
225f0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
22600 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
22610 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
22620 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
22630 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
22640 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
22650 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
22660 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
22670 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
22680 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
22690 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
226a0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
226b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
226c0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
226d0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
226e0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
226f0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
22700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
22710 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
22720 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
22730 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
22740 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
22750 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
22760 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22770 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
22780 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
22790 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
227a0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
227b0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
227c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
227d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
227e0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
227f0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
22800 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
22810 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
22820 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
22830 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
22840 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
22850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22860 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
22870 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
22880 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
22890 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
228a0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
228b0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
228c0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
228d0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
228e0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
228f0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
22900 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
22910 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
22920 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
22930 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
22940 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
22950 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
22960 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
22970 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
22980 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
22990 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
229a0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
229b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
229c0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
229d0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
229e0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
229f0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
22a00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22a10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
22a20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
22a30 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
22a40 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
22a50 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
22a60 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
22a70 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
22a80 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
22a90 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
22aa0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
22ab0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
22ac0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
22ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22ae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
22af0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
22b00 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
22b10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22b20 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
22b30 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
22b40 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22b50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22b60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22b70 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
22b80 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
22b90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22ba0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22bb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22bc0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
22bd0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
22be0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22bf0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22c10 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
22c20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
22c30 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22c40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22c50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22c60 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
22c70 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
22c80 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22c90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22cb0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
22cc0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
22cd0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22ce0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22cf0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22d00 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22d10 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
22d20 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22d30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22d40 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22d50 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
22d60 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22d70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22d80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22d90 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
22da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
22db0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22dc0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22dd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22de0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
22df0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
22e00 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22e10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22e20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22e30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
22e40 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
22e50 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22e60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22e70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e80 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
22e90 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
22ea0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22eb0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22ec0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22ed0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
22ee0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
22ef0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22f00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22f10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22f20 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
22f30 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
22f40 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22f50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f70 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
22f80 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
22f90 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22fa0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22fb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22fc0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
22fd0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
22fe0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22ff0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23010 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
23020 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
23030 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23040 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
23060 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
23070 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
23080 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23090 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
230a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
230b0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
230c0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
230d0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
230e0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
230f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
23100 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
23110 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
23120 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
23130 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
23140 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
23150 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
23160 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
23170 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
23180 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23190 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
231a0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
231b0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
231c0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
231d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
231e0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
231f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23200 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
23210 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
23220 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
23230 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
23240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
23250 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
23260 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23270 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23280 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
23290 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
232a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
232b0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
232c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
232d0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
232e0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
232f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
23300 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
23310 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23320 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
23330 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
23340 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23350 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23360 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23370 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
23380 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
23390 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
233a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
233b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
233c0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
233d0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
233e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
233f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
23400 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23410 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
23420 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
23430 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23440 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
23450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23460 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
23470 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
23480 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
23490 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
234a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
234b0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
234c0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
234d0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
234e0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
234f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23500 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
23510 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
23520 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
23530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
23540 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
23550 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
23560 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
23570 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
23580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
23590 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
235a0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
235b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
235c0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
235d0 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65  utines are depre
235e0 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  cated. Use the [
235f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23600 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
23610 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
23620 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62  routines describ
23630 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
23640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
23650 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
23660 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
23670 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
23680 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
23690 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
236a0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
236b0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
236c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
236d0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
236e0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
236f0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
23700 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
23710 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
23720 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
23730 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
23740 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
23750 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23760 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
23770 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
23780 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
23790 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
237a0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
237b0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
237c0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
237d0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
237e0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
237f0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
23800 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
23810 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
23820 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
23830 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
23840 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
23850 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
23860 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
23870 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
23880 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
23890 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
238a0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
238b0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
238c0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
238d0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
238e0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
238f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
23900 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
23910 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
23920 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
23930 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
23940 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
23950 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
23960 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
23970 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
23980 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
23990 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
239a0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
239b0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
239c0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
239d0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
239e0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
239f0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
23a00 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
23a10 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23a20 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
23a30 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
23a40 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
23a50 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
23a60 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
23a70 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
23a80 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
23a90 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
23aa0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
23ab0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
23ac0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
23ad0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
23ae0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
23af0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
23b00 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
23b10 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
23b20 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
23b30 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
23b40 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
23b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
23b60 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
23b70 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
23b80 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
23b90 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
23ba0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
23bb0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23bc0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  te..*/.SQLITE_DE
23bd0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
23be0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
23bf0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
23c00 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
23c10 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
23c20 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
23c30 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
23c40 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
23c50 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23c60 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
23c70 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
23c80 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
23c90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23ca0 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
23cb0 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
23cc0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
23cd0 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
23ce0 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
23cf0 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
23d00 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
23d10 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
23d20 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
23d30 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
23d40 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
23d50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
23d60 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
23d70 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61  trace_v2()] is a
23d80 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
23d90 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
23da0 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
23db0 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23dc0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
23dd0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
23de0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23df0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
23e00 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
23e10 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
23e20 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
23e30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
23e40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
23e50 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
23e60 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
23e70 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
23e80 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
23e90 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
23ea0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23eb0 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
23ec0 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
23ed0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23ee0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23ef0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
23f00 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
23f10 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
23f20 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
23f30 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
23f40 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23f50 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23f60 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23f70 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
23f80 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
23f90 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
23fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23fb0 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
23fc0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23fd0 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
23fe0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23ff0 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
24000 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
24010 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
24020 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
24030 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
24040 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
24050 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
24060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
24070 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
24080 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
24090 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
240a0 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
240b0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
240c0 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
240d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
240e0 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
240f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
24100 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
24110 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
24120 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
24130 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
24140 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
24150 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
24160 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
24170 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
24180 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
24190 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
241a0 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
241b0 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
241c0 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
241d0 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
241e0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
241f0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
24200 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
24210 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
24220 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
24230 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
24240 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
24250 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
24260 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
24270 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
24280 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
24290 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
242a0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
242b0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
242c0 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
242d0 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
242e0 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
242f0 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
24300 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
24310 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
24320 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
24330 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24340 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24350 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24360 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
24370 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
24380 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
24390 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
243a0 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
243b0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
243c0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
243d0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
243e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
243f0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
24400 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
24410 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
24420 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
24430 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
24440 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
24450 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
24460 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
24470 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
24480 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
24490 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
244a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
244b0 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
244c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
244d0 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
244e0 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
244f0 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
24500 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
24510 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
24520 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
24530 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
24540 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
24550 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24560 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
24570 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
24580 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
24590 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
245a0 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
245b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
245c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
245d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
245e0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
245f0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
24600 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
24610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
24620 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
24630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
24640 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
24650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24660 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
24670 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
24680 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
24690 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
246a0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
246b0 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
246c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
246d0 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
246e0 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
246f0 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
24700 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
24710 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
24720 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
24730 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
24740 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
24750 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
24760 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
24770 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
24780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
24790 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
247a0 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
247b0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
247c0 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
247d0 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
247e0 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
247f0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
24800 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
24810 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
24820 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
24830 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
24840 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
24850 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
24860 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
24870 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
24880 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
24890 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
248a0 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
248b0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
248c0 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
248d0 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
248e0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
248f0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
24900 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
24910 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
24920 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
24930 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
24940 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
24950 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
24960 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
24970 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
24980 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
24990 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
249a0 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
249b0 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
249c0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
249d0 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
249e0 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
249f0 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
24a00 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
24a10 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
24a20 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
24a30 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
24a40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24a50 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
24a60 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
24a70 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
24a80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
24a90 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24aa0 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
24ab0 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
24ac0 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
24ad0 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
24ae0 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
24af0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
24b00 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
24b10 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
24b20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
24b30 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
24b40 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
24b50 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
24b60 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24b70 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
24b80 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
24b90 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
24ba0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
24bb0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
24bc0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
24bd0 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
24be0 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
24bf0 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  ecated..*/.int s
24c00 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24c10 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75  .  sqlite3*,.  u
24c20 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20  nsigned uMask,. 
24c30 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29   int(*xCallback)
24c40 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c  (unsigned,void*,
24c50 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20  void*,void*),.  
24c60 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f  void *pCtx.);../
24c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
24c80 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
24c90 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
24ca0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
24cb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
24cc0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
24cd0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
24ce0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
24cf0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
24d00 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
24d10 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
24d20 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
24d30 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
24d40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
24d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24d60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
24d70 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
24d80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
24d90 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
24da0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
24db0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
24dc0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
24dd0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
24de0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
24df0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
24e00 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
24e10 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
24e20 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
24e30 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
24e40 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
24e50 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
24e60 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
24e70 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
24e80 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
24e90 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
24ea0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
24eb0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
24ec0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
24ed0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
24ee0 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
24ef0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
24f00 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
24f10 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
24f20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
24f30 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
24f40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24f50 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
24f60 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
24f70 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
24f80 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
24f90 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
24fa0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
24fb0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
24fc0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
24fd0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
24fe0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
24ff0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
25000 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
25010 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
25020 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
25030 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
25040 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
25050 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
25060 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
25070 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
25080 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
25090 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
250a0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
250b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
250c0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
250d0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
250e0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
250f0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
25100 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
25110 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
25120 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
25130 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
25140 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
25150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25160 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
25170 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
25180 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
25190 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
251a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
251b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
251c0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
251d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
251e0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
251f0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
25200 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
25210 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
25220 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
25230 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
25240 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
25250 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
25260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25270 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
25280 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25290 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
252a0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
252b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
252c0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
252d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
252e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
252f0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
25300 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
25310 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
25320 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25330 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
25340 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
25350 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
25360 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
25370 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
25380 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
25390 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
253a0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
253b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
253c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
253d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
253e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
253f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
25400 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
25410 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
25420 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
25430 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
25440 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
25450 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
25460 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
25470 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
25480 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
25490 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
254a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
254b0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
254c0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
254d0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
254e0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
254f0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
25500 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
25510 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
25520 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
25530 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
25540 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
25550 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
25560 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25570 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
25580 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
25590 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
255a0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
255b0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
255c0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
255d0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
255e0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
255f0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
25600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
25610 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
25620 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
25630 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
25640 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
25650 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
25660 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
25670 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
25680 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
25690 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
256a0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
256b0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
256c0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
256d0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
256e0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
256f0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
25700 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
25710 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
25720 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
25730 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
25740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
25750 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
25760 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
25770 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
25780 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
25790 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
257a0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
257b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
257c0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
257d0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
257e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
257f0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25800 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
25810 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
25820 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
25830 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
25840 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
25850 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
25860 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
25870 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
25880 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
25890 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
258a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
258b0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
258c0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
258d0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
258e0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
258f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
25900 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
25910 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25920 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
25930 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25940 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
25950 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
25960 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
25970 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
25980 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
25990 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
259a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
259b0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
259c0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
259d0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
259e0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
259f0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
25a00 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
25a10 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
25a20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25a30 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
25a40 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
25a50 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25a60 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
25a70 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
25a80 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
25a90 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
25aa0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
25ab0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
25ac0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
25ad0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
25ae0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
25af0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
25b00 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
25b10 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
25b20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
25b30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25b40 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
25b50 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
25b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
25b70 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25b80 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
25b90 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
25ba0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
25bb0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
25bc0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
25bd0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
25be0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
25bf0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
25c00 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
25c10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
25c20 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
25c30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
25c40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25c50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25c60 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
25c70 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
25c80 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
25c90 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
25ca0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
25cb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25cc0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
25cd0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
25ce0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25cf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25d00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
25d10 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
25d20 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
25d30 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
25d50 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
25d60 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
25d70 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
25d80 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
25d90 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
25da0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
25db0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25dc0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
25dd0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
25de0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
25df0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
25e00 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
25e20 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
25e30 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
25e40 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
25e50 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
25e60 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
25e70 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
25e80 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25e90 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
25ea0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25eb0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
25ec0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
25ed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
25ee0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
25ef0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
25f00 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
25f10 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
25f20 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
25f30 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
25f40 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
25f50 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
25f60 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
25f70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25f80 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
25f90 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
25fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25fb0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
25fc0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
25fd0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
25fe0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
25ff0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
26000 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26010 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
26020 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
26030 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
26040 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
26050 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
26060 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
26070 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
26080 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
26090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
260a0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
260b0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
260c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
260d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
260e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
260f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
26100 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
26110 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
26120 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
26130 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
26140 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
26150 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
26160 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
26170 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
26180 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
26190 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
261a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
261b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
261c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
261d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
261e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
261f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
26200 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
26210 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
26220 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
26230 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
26240 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
26250 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
26260 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
26270 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
26280 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
26290 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
262a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
262b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
262c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
262d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
262e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
262f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
26300 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
26310 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
26320 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
26330 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
26340 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
26350 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
26360 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
26370 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
26380 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
26390 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
263a0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
263b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
263c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
263d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
263e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
263f0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
26400 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
26410 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
26420 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
26430 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
26440 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26450 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
26460 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
26470 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
26480 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
26490 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
264a0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
264b0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
264c0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
264d0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
264e0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
264f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
26500 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26510 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
26520 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
26530 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
26540 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
26550 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
26560 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
26570 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
26580 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
26590 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
265a0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
265b0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66  option..** URI f
265c0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
265d0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
265e0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
265f0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
26600 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
26610 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
26620 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
26630 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
26640 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
26650 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
26660 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
26670 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
26680 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
26690 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
266a0 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
266b0 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
266c0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
266d0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
266e0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
266f0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
26700 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
26710 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
26720 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
26730 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
26740 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
26750 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
26760 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
26770 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
26780 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
26790 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
267a0 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
267b0 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
267c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
267d0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
267e0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
267f0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
26800 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
26810 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
26820 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
26830 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
26840 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
26850 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
26860 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
26870 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
26880 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
26890 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
268a0 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
268b0 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
268c0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
268d0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
268e0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
268f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
26900 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
26910 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
26920 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
26930 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
26940 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
26950 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
26960 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
26970 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
26980 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
26990 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
269a0 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
269b0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
269c0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
269d0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
269e0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
269f0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
26a00 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
26a10 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
26a20 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
26a30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
26a40 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
26a50 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
26a60 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
26a70 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
26a80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
26a90 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
26aa0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
26ab0 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
26ac0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
26ad0 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
26ae0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
26af0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
26b00 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
26b10 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
26b20 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
26b30 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
26b40 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
26b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26b60 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
26b70 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
26b80 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
26b90 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
26ba0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
26bb0 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
26bc0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
26bd0 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
26be0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
26bf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26c00 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
26c10 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
26c20 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
26c30 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
26c40 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
26c50 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
26c60 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
26c70 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
26c80 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
26c90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26ca0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26cb0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
26cc0 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
26cd0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
26ce0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26cf0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
26d00 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
26d10 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
26d20 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
26d30 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
26d40 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
26d50 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
26d60 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
26d70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
26d80 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26d90 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
26da0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
26db0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
26dc0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
26dd0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
26de0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
26df0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
26e00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
26e10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
26e20 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
26e30 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
26e40 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
26e50 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26e60 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
26e70 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
26e80 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
26e90 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
26ea0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
26eb0 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
26ec0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
26ed0 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
26ee0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
26ef0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
26f00 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
26f10 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
26f20 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
26f30 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
26f40 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
26f50 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
26f60 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
26f70 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
26f80 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
26f90 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
26fa0 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
26fb0 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
26fc0 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
26fd0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
26fe0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
26ff0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
27000 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
27010 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
27020 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
27030 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
27040 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
27050 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
27060 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
27070 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27080 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
27090 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
270a0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
270b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
270c0 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
270d0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
270e0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
270f0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
27100 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27110 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
27120 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
27130 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
27140 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
27150 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
27160 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
27170 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
27180 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
27190 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
271a0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
271b0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
271c0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
271d0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
271e0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
271f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27200 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
27210 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
27220 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
27230 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
27240 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
27250 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
27260 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
27270 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
27280 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
27290 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
272a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
272b0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
272c0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
272d0 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
272e0 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
272f0 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
27300 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
27310 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
27320 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
27330 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
27340 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
27350 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
27360 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
27370 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
27380 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
27390 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
273a0 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
273b0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
273c0 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
273d0 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
273e0 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
273f0 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
27400 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
27410 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
27420 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
27430 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
27440 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
27450 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
27460 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
27470 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
27480 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
27490 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
274a0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
274b0 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
274c0 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
274d0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
274e0 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
274f0 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
27500 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
27510 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
27520 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
27530 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
27540 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
27550 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
27560 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
27570 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
27580 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
27590 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
275a0 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
275b0 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
275c0 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
275d0 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
275e0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
275f0 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
27600 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
27610 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
27620 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
27630 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
27640 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
27650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
27660 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
27670 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
27680 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
27690 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
276a0 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
276b0 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
276c0 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
276d0 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
276e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
276f0 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
27700 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
27710 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
27720 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
27730 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
27740 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
27750 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
27760 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
27770 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
27780 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
27790 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
277a0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
277b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
277c0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
277d0 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
277e0 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
277f0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
27800 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
27810 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
27820 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
27830 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
27840 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
27850 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
27860 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
27870 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
27880 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
27890 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
278a0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
278b0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
278c0 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
278d0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
278e0 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
278f0 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
27900 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
27910 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
27920 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
27930 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27940 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
27950 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
27960 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
27970 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
27980 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
27990 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
279a0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
279b0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
279c0 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
279d0 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
279e0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
279f0 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
27a00 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
27a10 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27a20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
27a30 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
27a40 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
27a50 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27a60 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
27a70 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
27a80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
27a90 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
27aa0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
27ab0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
27ac0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
27ad0 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
27ae0 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
27af0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
27b00 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
27b10 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
27b20 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
27b30 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
27b40 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
27b50 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
27b60 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
27b70 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
27b80 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
27b90 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
27ba0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
27bb0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
27bc0 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
27bd0 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
27be0 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
27bf0 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
27c00 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
27c10 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
27c20 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
27c30 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
27c40 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
27c50 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
27c60 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
27c70 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
27c80 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
27c90 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
27ca0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
27cb0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
27cc0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
27cd0 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
27ce0 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
27cf0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
27d00 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
27d10 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
27d20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27d30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27d40 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
27d50 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
27d60 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
27d70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27d80 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
27d90 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
27da0 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
27db0 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
27dc0 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
27dd0 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
27de0 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
27df0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
27e00 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
27e10 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
27e20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
27e30 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
27e40 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
27e50 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
27e60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
27e70 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
27e80 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
27e90 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
27ea0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
27eb0 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
27ec0 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
27ed0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
27ee0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
27ef0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
27f00 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
27f10 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
27f20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
27f30 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
27f40 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
27f50 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
27f60 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
27f70 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
27f80 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
27f90 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
27fa0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
27fb0 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
27fc0 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
27fd0 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
27fe0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
27ff0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
28000 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
28010 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
28020 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
28030 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
28040 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
28050 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
28060 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
28070 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
28080 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
28090 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
280a0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
280b0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
280c0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
280d0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
280e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
280f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
28100 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28110 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
28120 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
28130 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
28140 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
28150 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
28160 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
28170 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
28180 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
28190 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
281a0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
281b0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
281c0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
281d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
281e0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
281f0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
28200 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
28210 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
28220 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
28230 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
28240 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
28250 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
28260 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
28270 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
28280 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
28290 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
282a0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
282b0 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
282c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
282d0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
282e0 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
282f0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
28300 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
28310 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
28320 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
28330 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
28340 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
28350 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
28360 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
28370 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
28380 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
28390 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
283a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
283b0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
283c0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
283d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
283e0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
283f0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
28400 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
28410 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
28420 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
28430 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
28440 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
28450 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
28460 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
28470 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
28480 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
28490 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
284a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
284b0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
284c0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
284d0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
284e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
284f0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
28500 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
28510 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
28520 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
28530 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
28540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
28550 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
28560 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
28570 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
28580 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
28590 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
285a0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
285b0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
285c0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
285d0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
285e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
285f0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
28600 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
28610 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
28620 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
28630 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
28640 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
28650 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
28660 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
28670 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
28680 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
28690 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
286a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
286b0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
286c0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
286d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
286e0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
286f0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
28700 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28710 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
28720 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
28730 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
28740 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
28750 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
28760 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
28770 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
28780 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
28790 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
287a0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
287b0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
287c0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
287d0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
287e0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
287f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
28800 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
28810 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28820 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28830 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
28840 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
28850 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
28860 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
28870 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
28880 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
28890 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
288a0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
288b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
288c0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
288d0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
288e0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
288f0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
28900 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
28910 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
28920 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
28930 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
28940 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
28950 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
28960 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
28970 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28980 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
28990 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
289a0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
289b0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
289c0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
289d0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
289e0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
289f0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
28a00 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
28a10 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
28a20 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
28a30 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
28a40 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
28a50 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
28a60 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
28a70 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
28a80 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
28a90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28aa0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
28ab0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
28ac0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
28ad0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
28ae0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
28af0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
28b00 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
28b10 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
28b20 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
28b30 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
28b40 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
28b50 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
28b60 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
28b70 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
28b80 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
28b90 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
28ba0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
28bb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28bc0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
28bd0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
28be0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
28bf0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
28c00 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28c10 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
28c20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
28c30 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
28c40 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
28c50 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
28c60 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
28c70 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
28c80 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
28c90 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
28ca0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
28cb0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
28cc0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
28cd0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
28ce0 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
28cf0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
28d00 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
28d10 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
28d20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
28d30 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
28d40 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
28d50 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
28d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
28d70 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
28d80 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
28d90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
28da0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
28db0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
28dc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
28dd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
28de0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
28df0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
28e00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28e10 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
28e20 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
28e30 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
28e40 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
28e50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28e60 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
28e70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
28e80 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
28e90 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
28ea0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
28eb0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
28ec0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
28ed0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
28ee0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
28ef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
28f00 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
28f10 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
28f20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
28f30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
28f40 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
28f50 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
28f60 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
28f70 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
28f80 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
28f90 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
28fa0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
28fb0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
28fc0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
28fd0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
28fe0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
28ff0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
29000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29010 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
29020 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
29030 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
29040 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
29050 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
29060 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
29070 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
29080 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
29090 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
290a0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
290b0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
290c0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
290d0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
290e0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
290f0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
29100 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
29110 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
29120 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
29130 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
29140 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
29150 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
29160 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
29170 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
29180 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
29190 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
291a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
291b0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
291c0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
291d0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
291e0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
291f0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
29200 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
29210 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29220 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29230 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29240 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29250 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
29260 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
29270 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
29280 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
29290 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
292a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
292b0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
292c0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
292d0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
292e0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
292f0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
29300 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
29310 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
29320 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
29330 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
29340 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
29350 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
29360 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
29370 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
29380 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
29390 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
293a0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
293b0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
293c0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
293d0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
293e0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
293f0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
29400 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
29410 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
29420 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
29430 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
29440 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
29450 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
29460 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
29470 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
29480 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
29490 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
294a0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
294b0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
294c0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
294d0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
294e0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
294f0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
29500 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
29510 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
29520 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
29530 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
29540 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
29550 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
29560 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
29570 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
29580 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
29590 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
295a0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
295b0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
295c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
295d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
295e0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
295f0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
29600 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
29610 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
29620 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29630 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
29640 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
29650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
29660 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
29670 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
29680 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
29690 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
296a0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
296b0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
296c0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
296d0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
296e0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
296f0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
29700 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
29710 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
29720 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
29730 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
29740 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
29750 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
29760 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
29770 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
29780 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
29790 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
297a0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
297b0 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
297c0 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
297d0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
297e0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
297f0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
29800 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
29810 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
29820 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
29830 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
29840 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
29850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
29860 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
29870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
29880 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
29890 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
298a0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
298b0 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
298c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
298d0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
298e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
298f0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
29900 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
29910 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
29920 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
29930 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
29940 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
29950 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
29960 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
29970 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
29980 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
29990 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
299a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
299b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
299c0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
299d0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
299e0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
299f0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
29a00 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
29a10 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
29a20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
29a30 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
29a40 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
29a50 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
29a60 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
29a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29a80 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
29a90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
29aa0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
29ab0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
29ac0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
29ad0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
29ae0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
29af0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
29b00 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
29b10 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
29b20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
29b30 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
29b40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
29b50 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
29b60 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
29b70 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
29b80 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
29b90 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
29ba0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
29bb0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
29bc0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
29bd0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
29be0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
29bf0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
29c00 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
29c10 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
29c20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
29c30 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
29c40 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
29c50 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
29c60 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
29c70 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
29c80 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
29c90 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
29ca0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
29cb0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
29cc0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
29cd0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
29ce0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
29cf0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
29d00 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
29d10 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
29d20 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
29d30 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
29d40 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
29d50 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
29d60 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
29d70 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
29d80 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
29d90 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
29da0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
29db0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
29dc0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
29dd0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
29de0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
29df0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
29e00 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
29e10 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
29e20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
29e30 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
29e40 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
29e50 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
29e60 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
29e70 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
29e80 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
29e90 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
29ea0 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
29eb0 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
29ec0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29ed0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
29ee0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
29ef0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
29f00 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
29f10 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
29f20 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
29f30 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
29f40 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
29f50 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
29f60 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
29f70 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
29f80 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
29f90 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
29fa0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
29fb0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
29fc0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
29fd0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
29fe0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
29ff0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
2a000 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
2a010 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
2a020 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
2a030 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
2a040 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
2a050 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
2a060 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
2a070 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
2a080 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
2a090 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
2a0a0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
2a0b0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
2a0c0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
2a0d0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
2a0e0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
2a0f0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
2a100 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
2a110 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
2a120 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
2a130 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
2a140 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
2a150 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
2a160 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
2a170 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
2a180 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
2a190 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2a1a0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
2a1b0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
2a1c0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
2a1d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
2a1e0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
2a1f0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
2a200 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
2a210 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
2a220 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2a230 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
2a240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
2a250 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
2a260 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
2a270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a280 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
2a290 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
2a2a0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
2a2b0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
2a2c0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
2a2d0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2a2e0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2a2f0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
2a300 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
2a310 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
2a320 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
2a330 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2a340 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
2a350 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
2a360 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
2a370 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
2a380 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
2a390 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2a3a0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
2a3b0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
2a3c0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
2a3d0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2a3e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a3f0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2a400 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
2a410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a420 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
2a430 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
2a440 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
2a450 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
2a460 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a470 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a480 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a490 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a4a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a4b0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2a4c0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
2a4d0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
2a4e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a4f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a500 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
2a510 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
2a520 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a530 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2a540 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
2a550 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
2a560 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
2a570 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2a580 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
2a590 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
2a5a0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
2a5b0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
2a5c0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
2a5d0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
2a5e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a5f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2a600 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a610 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2a620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a630 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
2a640 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
2a650 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
2a660 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2a670 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a680 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
2a690 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a6a0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2a6b0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
2a6c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a6d0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
2a6e0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
2a6f0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
2a700 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a710 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2a720 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a730 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
2a740 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a750 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2a760 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
2a770 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
2a780 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
2a790 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
2a7a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2a7b0 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72    If [sqlite3_pr
2a7c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
2a7d0 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  * the equivalent
2a7e0 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61   tries to alloca
2a7f0 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72  te space for mor
2a800 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79  e than this many
2a810 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61   opcodes.** in a
2a820 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64   single prepared
2a830 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53   statement, an S
2a840 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f  QLITE_NOMEM erro
2a850 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
2a860 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a870 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a880 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
2a890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2a8a0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
2a8b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a8c0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
2a8d0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
2a8e0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2a8f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a900 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
2a910 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
2a920 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
2a930 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a940 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
2a950 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
2a960 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
2a970 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a980 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2a990 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
2a9a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a9b0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2a9c0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a9d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2a9e0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
2a9f0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
2aa00 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
2aa10 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
2aa20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2aa30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2aa40 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
2aa50 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2aa60 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2aa70 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
2aa80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
2aa90 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
2aaa0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
2aab0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2aac0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
2aad0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2aae0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2aaf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2ab00 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
2ab10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ab20 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
2ab30 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
2ab40 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2ab50 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ab60 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
2ab70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2ab80 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2ab90 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
2aba0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2abb0 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
2abc0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
2abd0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
2abe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abf0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
2ac00 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
2ac10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ac20 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
2ac30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ac40 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
2ac50 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2ac60 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2ac70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2ac80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
2ac90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aca0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2acb0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2acc0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
2acd0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2ace0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2acf0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
2ad00 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2ad10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2ad20 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
2ad30 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
2ad40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2ad50 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
2ad60 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
2ad70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
2ad80 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
2ad90 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
2ada0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2adb0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2adc0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
2add0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ade0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
2adf0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
2ae00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ae10 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
2ae20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
2ae30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2ae40 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2ae50 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
2ae60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
2ae70 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a  repare Flags.**.
2ae80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2ae90 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2aea0 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e  s flags that can
2aeb0 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a   be passed into.
2aec0 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70  ** "prepFlags" p
2aed0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2aee0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aef0 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  _v3()] and.** [s
2af00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2af10 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v3()] interface
2af20 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61  s..**.** New fla
2af30 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  gs may be added 
2af40 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2af50 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
2af60 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2af70 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2af80 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e  SISTENT]] ^(<dt>
2af90 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2afa0 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a  ERSISTENT</dt>.*
2afb0 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2afc0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2afd0 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69  ENT flag is a hi
2afe0 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20  nt to the query 
2aff0 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20  planner.** that 
2b000 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2b010 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72  tement will be r
2b020 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f  etained for a lo
2b030 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70  ng time and.** p
2b040 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d  robably reused m
2b050 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69  any times.)^ ^Wi
2b060 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c  thout this flag,
2b070 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b080 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  e_v3()].** and [
2b090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b0a0 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74  6_v3()] assume t
2b0b0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2b0c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2b0d0 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74  .** be used just
2b0e0 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74   once or at most
2b0f0 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64   a few times and
2b100 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20   then destroyed 
2b110 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2b120 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65  3_finalize()] re
2b130 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54  latively soon. T
2b140 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
2b150 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a  mentation acts.*
2b160 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62  * on this hint b
2b170 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75  y avoiding the u
2b180 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65  se of [lookaside
2b190 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e   memory] so as n
2b1a0 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65  ot to.** deplete
2b1b0 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f   the limited sto
2b1c0 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  re of lookaside 
2b1d0 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76  memory. Future v
2b1e0 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51  ersions of.** SQ
2b1f0 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20  Lite may act on 
2b200 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72  this hint differ
2b210 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ently..** </dl>.
2b220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b230 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2b240 54 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  TENT            
2b250 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x01../*.** CA
2b260 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
2b270 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
2b280 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
2b290 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
2b2a0 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  ompiler}.** METH
2b2b0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43  OD: sqlite3.** C
2b2c0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
2b2d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
2b2e0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
2b2f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d   statement, it m
2b300 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
2b310 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
2b320 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
2b330 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
2b340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20  hese routines.  
2b350 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  Or, in other wor
2b360 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ds, these routin
2b370 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72  es.** are constr
2b380 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b  uctors for the [
2b390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b3a0 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  nt] object..**.*
2b3b0 2a 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20  * The preferred 
2b3c0 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69  routine to use i
2b3d0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2b3e0 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a  re_v2()].  The.*
2b3f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b400 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  re()] interface 
2b410 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68  is legacy and sh
2b420 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2b430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b440 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61  pare_v3()] has a
2b450 6e 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61  n extra "prepFla
2b460 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20  gs" option that 
2b470 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73  is used.** for s
2b480 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e  pecial purposes.
2b490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f  .**.** The use o
2b4a0 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65  f the UTF-8 inte
2b4b0 72 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72  rfaces is prefer
2b4c0 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63  red, as SQLite c
2b4d0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73  urrently.** does
2b4e0 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69   all parsing usi
2b4f0 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55  ng UTF-8.  The U
2b500 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73  TF-16 interfaces
2b510 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
2b520 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   as a convenienc
2b530 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69  e.  The UTF-16 i
2b540 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62  nterfaces work b
2b550 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65  y converting the
2b560 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69  .** input text i
2b570 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20  nto UTF-8, then 
2b580 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72  invoking the cor
2b590 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38  responding UTF-8
2b5a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2b5b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
2b5c0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
2b5d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b5e0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
2b5f0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
2b600 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2b610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2b620 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2b630 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
2b640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2b650 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
2b660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2b670 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
2b680 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
2b690 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b6a0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
2b6b0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2b6c0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
2b6d0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
2b6e0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
2b6f0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
2b700 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33  epare(), sqlite3
2b710 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a  _prepare_v2(),.*
2b720 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2b730 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e  epare_v3().** in
2b740 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
2b750 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
2b760 70 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c  prepare16(), sql
2b770 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b780 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2b790 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2b7a0 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  () use UTF-16..*
2b7b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
2b7c0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e  te argument is n
2b7d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53  egative, then zS
2b7e0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
2b7f0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
2b800 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
2b810 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69  If nByte is posi
2b820 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
2b830 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2b840 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  f bytes read fro
2b850 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79  m zSql.  ^If nBy
2b860 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  te is zero, then
2b870 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20   no prepared.** 
2b880 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e  statement is gen
2b890 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68  erated..** If th
2b8a0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74  e caller knows t
2b8b0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
2b8c0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
2b8d0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a  erminated, then.
2b8e0 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  ** there is a sm
2b8f0 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  all performance 
2b900 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73  advantage to pas
2b910 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
2b920 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
2b930 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2b940 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
2b950 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
2b960 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
2b970 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
2b980 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  r..**.** ^If pzT
2b990 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
2b9a0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
2b9b0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2b9c0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
2b9d0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
2b9e0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
2b9f0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2ba00 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
2ba10 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
2ba20 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
2ba30 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
2ba40 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
2ba50 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
2ba60 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
2ba70 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
2ba80 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
2ba90 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
2baa0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
2bab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2bac0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
2bad0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
2bae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
2baf0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
2bb00 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
2bb10 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
2bb20 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
2bb30 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
2bb40 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
2bb50 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
2bb60 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
2bb70 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
2bb80 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
2bb90 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
2bba0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
2bbb0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
2bbc0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2bbd0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
2bbe0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2bbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2bc00 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
2bc10 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2bc20 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
2bc30 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
2bc40 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
2bc50 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
2bc60 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
2bc70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2bc80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
2bc90 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
2bca0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2bcb0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
2bcc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bcd0 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v2(), sqlite3_p
2bce0 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c  repare_v3(), sql
2bcf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bd00 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2bd10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2bd20 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2bd30 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  e recommended fo
2bd40 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
2bd50 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72  ms..** The older
2bd60 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c   interfaces (sql
2bd70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
2bd80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2bd90 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72  re16()).** are r
2bda0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
2bdb0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2bdc0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
2bdd0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
2bde0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
2bdf0 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  X" interfaces, t
2be00 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2be10 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
2be20 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
2be30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2be40 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
2be50 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2be60 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
2be70 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
2be80 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2be90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
2bea0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
2beb0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
2bec0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
2bed0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2bee0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2bef0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
2bf00 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
2bf10 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
2bf20 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
2bf30 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
2bf40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2bf50 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2bf60 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
2bf70 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2bf80 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
2bf90 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
2bfa0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
2bfb0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
2bfc0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
2bfd0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
2bfe0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
2bff0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
2c000 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
2c010 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2c020 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
2c030 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
2c040 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
2c050 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
2c060 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
2c070 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
2c080 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2c090 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
2c0a0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
2c0b0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
2c0c0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
2c0d0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
2c0e0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
2c0f0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
2c100 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
2c110 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
2c120 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
2c130 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
2c140 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
2c150 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2c160 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
2c170 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
2c180 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
2c190 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
2c1a0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
2c1b0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
2c1c0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
2c1d0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
2c1e0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
2c1f0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
2c200 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
2c210 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
2c220 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
2c230 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2c240 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
2c250 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
2c260 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
2c270 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
2c280 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
2c290 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
2c2a0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
2c2b0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2c2c0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
2c2d0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
2c2e0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
2c2f0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
2c300 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2c310 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
2c320 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
2c330 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2c340 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
2c350 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
2c360 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
2c370 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
2c380 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
2c390 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
2c3a0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
2c3b0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
2c3c0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
2c3d0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
2c3e0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
2c3f0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
2c400 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
2c410 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
2c420 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
2c430 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
2c440 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
2c450 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
2c460 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
2c470 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
2c480 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
2c490 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33  *.** <p>^sqlite3
2c4a0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69  _prepare_v3() di
2c4b0 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74  ffers from sqlit
2c4c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2c4d0 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a  only in having.*
2c4e0 2a 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70  * the extra prep
2c4f0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c  Flags parameter,
2c500 20 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20   which is a bit 
2c510 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67  array consisting
2c520 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d   of zero or.** m
2c530 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
2c540 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2c550 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45  STENT|SQLITE_PRE
2c560 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20  PARE_*] flags.  
2c570 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2c580 70 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74  prepare_v2() int
2c590 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61  erface works exa
2c5a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
2c5b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2c5c0 61 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20  are_v3() with a 
2c5d0 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70  zero prepFlags p
2c5e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f  arameter..** </o
2c5f0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
2c600 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2c610 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c620 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c630 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c640 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2c650 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c660 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2c670 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c680 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c690 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c6a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c6b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2c6c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2c6d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2c6e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2c6f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2c700 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2c710 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2c720 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2c730 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2c740 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c750 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c760 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c770 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2c780 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c790 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2c7a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2c7b0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2c7c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2c7d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2c7e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2c7f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2c800 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2c810 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2c820 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2c830 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c840 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2c850 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2c860 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2c870 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2c880 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2c890 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  re_v3(.  sqlite3
2c8a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c8b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c8c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c8d0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2c8e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2c8f0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2c900 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2c910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c920 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2c930 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2c940 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20  . */.  unsigned 
2c950 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f  int prepFlags, /
2c960 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53  * Zero or more S
2c970 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66  QLITE_PREPARE_ f
2c980 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65  lags */.  sqlite
2c990 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c9a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c9b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c9c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c9d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c9e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c9f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2ca00 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2ca10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2ca20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2ca30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ca40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2ca50 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ca60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ca70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ca80 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ca90 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2caa0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2cab0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2cac0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2cad0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2cae0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2caf0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2cb00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2cb10 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2cb20 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2cb30 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2cb40 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2cb50 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2cb60 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2cb70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2cb80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2cb90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cba0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2cbb0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2cbc0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2cbd0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2cbe0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2cbf0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2cc00 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2cc10 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2cc20 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2cc30 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2cc40 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2cc50 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2cc60 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2cc70 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2cc80 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2cc90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2cca0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2ccb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ccc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2ccd0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2cce0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2ccf0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2cd00 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2cd10 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2cd20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2cd30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2cd40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2cd50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2cd60 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70    unsigned int p
2cd70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72  repFlags, /* Zer
2cd80 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45  o or more SQLITE
2cd90 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20  _PREPARE_ flags 
2cda0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2cdb0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2cdc0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2cdd0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cde0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2cdf0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2ce00 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2ce10 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ce20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce30 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
2ce40 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20  tatement SQL.** 
2ce50 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ce60 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2ce70 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2ce80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ce90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2cea0 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d  copy of the UTF-
2ceb0 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  8.** SQL text us
2cec0 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72  ed to create [pr
2ced0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cee0 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20  ] P if P was.** 
2cef0 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
2cf00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cf10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
2cf20 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v3()],.** [s
2cf30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cf40 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  _v2()], or [sqli
2cf50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2cf60 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
2cf70 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2cf80 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2cf90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2cfa0 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73   to a UTF-8.** s
2cfb0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2cfc0 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66   the SQL text of
2cfd0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cfe0 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62  ent P with.** [b
2cff0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d  ound parameters]
2d000 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a   expanded..**.**
2d010 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2d020 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  if a prepared st
2d030 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74  atement is creat
2d040 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
2d050 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54  .** text "SELECT
2d060 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20   $abc,:xyz" and 
2d070 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62  if parameter $ab
2d080 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e  c is bound to in
2d090 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e  teger 2345.** an
2d0a0 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a  d parameter :xyz
2d0b0 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65   is unbound, the
2d0c0 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20  n sqlite3_sql() 
2d0d0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74  will return.** t
2d0e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69  he original stri
2d0f0 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63  ng, "SELECT $abc
2d100 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74  ,:xyz" but sqlit
2d110 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d120 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2d130 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55   "SELECT 2345,NU
2d140 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  LL".)^.**.** ^Th
2d150 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2d160 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61  ed_sql() interfa
2d170 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  ce returns NULL 
2d180 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
2d190 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61  memory.** is ava
2d1a0 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74  ilable to hold t
2d1b0 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66  he result, or if
2d1c0 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c   the result woul
2d1d0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2d1e0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69  the maximum stri
2d1f0 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d  ng length determ
2d200 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c  ined by the [SQL
2d210 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2d220 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  ]..**.** ^The [S
2d230 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
2d240 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
2d250 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69  time option limi
2d260 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ts the size of.*
2d270 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  * bound paramete
2d280 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e  r expansions.  ^
2d290 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2d2a0 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
2d2b0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63  time.** option c
2d2c0 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78  auses sqlite3_ex
2d2d0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20  panded_sql() to 
2d2e0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55  always return NU
2d2f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2d300 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2d310 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  y sqlite3_sql(P)
2d320 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53   is managed by S
2d330 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20  QLite and is.** 
2d340 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2d350 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65  eed when the pre
2d360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d370 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  is finalized..**
2d380 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2d390 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d3a0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2d3b0 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68  , on the other h
2d3c0 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69  and,.** is obtai
2d3d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d3e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
2d3f0 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20  must be free by 
2d400 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2d410 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ** by passing it
2d420 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
2d430 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  e()]..*/.const c
2d440 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2d450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d460 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  Stmt);.char *sql
2d470 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d480 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2d490 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d4a0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2d4b0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
2d4c0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
2d4d0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45  e Database.** ME
2d4e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2d4f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2d500 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2d510 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
2d520 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2d530 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
2d540 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
2d550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d560 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
2d570 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
2d580 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2d590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d5a0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
2d5b0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
2d5c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d5d0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
2d5e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2d5f0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
2d600 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
2d610 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
2d620 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
2d630 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2d640 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2d650 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
2d660 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
2d670 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
2d680 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
2d690 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
2d6a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
2d6b0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
2d6c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
2d6d0 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
2d6e0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
2d6f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
2d700 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
2d710 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
2d720 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
2d730 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2d740 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
2d750 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
2d760 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d770 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2d780 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
2d790 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
2d7a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d7b0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
2d7c0 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
2d7d0 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
2d7e0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
2d7f0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
2d800 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
2d810 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
2d820 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
2d830 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
2d840 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d850 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2d860 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
2d870 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
2d880 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
2d890 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
2d8a0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
2d8b0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
2d8c0 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
2d8d0 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
2d8e0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
2d8f0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
2d900 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
2d910 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
2d920 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
2d930 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
2d940 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d950 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
2d960 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
2d970 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
2d980 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
2d990 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
2d9a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d9b0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
2d9c0 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
2d9d0 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
2d9e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2d9f0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a  iles on disk..**
2da00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2da10 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e  mt_readonly() in
2da20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2da30 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d  true for [BEGIN]
2da40 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e   since.** [BEGIN
2da50 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e  ] merely sets in
2da60 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75  ternal flags, bu
2da70 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47  t the [BEGIN|BEG
2da80 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e  IN IMMEDIATE] an
2da90 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49  d.** [BEGIN|BEGI
2daa0 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d  N EXCLUSIVE] com
2dab0 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74  mands do touch t
2dac0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
2dad0 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  so.** sqlite3_st
2dae0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65  mt_readonly() re
2daf0 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20  turns false for 
2db00 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a  those commands..
2db10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2db20 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
2db30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2db40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2db50 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2db60 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2db70 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
2db80 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
2db90 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2dba0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dbb0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
2dbc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2dbd0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2dbe0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2dbf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2dc00 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
2dc10 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
2dc20 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2dc30 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
2dc40 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
2dc50 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
2dc60 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2dc70 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
2dc80 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
2dc90 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
2dca0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2dcb0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
2dcc0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2dcd0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
2dce0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
2dcf0 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
2dd00 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
2dd10 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
2dd20 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
2dd30 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
2dd40 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
2dd50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2dd60 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
2dd70 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2dd80 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2dd90 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
2dda0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2ddb0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2ddc0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
2ddd0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
2dde0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
2ddf0 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
2de00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
2de10 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
2de20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
2de30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
2de40 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
2de50 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
2de60 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
2de70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
2de80 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
2de90 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
2dea0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
2deb0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
2dec0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
2ded0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
2dee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2def0 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
2df00 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2df10 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
2df20 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
2df30 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2df40 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
2df50 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
2df60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2df70 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
2df80 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2df90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2dfa0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
2dfb0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
2dfc0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
2dfd0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
2dfe0 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
2dff0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
2e000 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
2e010 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
2e020 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
2e030 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
2e040 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
2e050 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
2e060 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2e070 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
2e080 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
2e090 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
2e0a0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
2e0b0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
2e0c0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
2e0d0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
2e0e0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2e0f0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
2e100 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
2e110 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
2e120 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
2e130 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
2e140 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
2e150 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e160 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
2e170 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
2e180 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
2e190 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
2e1a0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
2e1b0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
2e1c0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
2e1d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
2e1e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
2e1f0 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
2e200 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2e210 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
2e220 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
2e230 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e240 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
2e250 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e260 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
2e270 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
2e280 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
2e290 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
2e2a0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
2e2b0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
2e2c0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
2e2d0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
2e2e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2e2f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2e300 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
2e310 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
2e320 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2e330 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
2e340 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2e350 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
2e360 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
2e370 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
2e380 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
2e390 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
2e3a0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
2e3b0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
2e3c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
2e3d0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
2e3e0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
2e3f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
2e400 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
2e410 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2e420 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
2e430 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
2e440 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
2e450 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2e460 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2e470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2e480 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
2e490 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
2e4a0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
2e4b0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
2e4c0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
2e4d0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
2e4e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
2e4f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2e500 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
2e510 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2e520 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2e530 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2e540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e550 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
2e560 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
2e570 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
2e580 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2e590 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
2e5a0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
2e5b0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
2e5c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2e5d0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
2e5e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2e5f0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
2e600 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
2e610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e620 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2e630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e640 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2e650 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
2e660 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
2e670 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e680 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
2e690 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a  ed as arguments.
2e6a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ** to [sqlite3_r
2e6b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20  esult_value()], 
2e6c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2e6d0 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  lue()], and.** [
2e6e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2e6f0 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  p()]..** The [sq
2e700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2e710 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
2e720 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
2e730 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2e740 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
2e750 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e760 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
2e770 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2e780 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65  te3_value sqlite
2e790 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
2e7a0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
2e7b0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
2e7c0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2e7d0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
2e7e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2e7f0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
2e800 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
2e810 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2e820 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
2e830 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
2e840 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
2e850 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
2e860 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
2e870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e880 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2e890 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
2e8a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e8b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2e8c0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
2e8d0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
2e8e0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
2e8f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2e900 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
2e910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
2e920 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
2e930 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e940 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
2e950 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
2e960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2e970 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
2e980 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2e990 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
2e9a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2e9b0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
2e9c0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2e9d0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
2e9e0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
2e9f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
2ea00 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
2ea10 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ea20 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
2ea30 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2ea40 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2ea50 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
2ea60 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
2ea70 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
2ea80 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
2ea90 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
2eaa0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
2eab0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2eac0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
2ead0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2eae0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2eaf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2eb00 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2eb10 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2eb20 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2eb30 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2eb40 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2eb50 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2eb60 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2eb70 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2eb80 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2eb90 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2eba0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2ebb0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2ebc0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2ebd0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2ebe0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2ebf0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2ec00 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2ec10 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2ec20 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2ec30 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2ec40 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2ec50 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2ec60 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2ec70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2ec80 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2ec90 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2eca0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2ecb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ecc0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2ecd0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2ece0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2ecf0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2ed00 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2ed10 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2ed20 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2ed30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2ed40 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2ed50 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2ed60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ed70 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2ed80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2ed90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2eda0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2edb0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2edc0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2edd0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2ede0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2edf0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2ee00 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2ee10 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2ee20 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2ee30 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2ee40 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2ee50 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2ee60 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2ee70 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2ee80 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2ee90 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2eea0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2eeb0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2eec0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2eed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2eee0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2eef0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2ef00 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2ef10 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2ef20 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2ef30 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2ef40 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2ef50 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2ef60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2ef70 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2ef80 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2ef90 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2efa0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2efb0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2efc0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2efd0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2efe0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2eff0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
2f000 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f010 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f020 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2f030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f040 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
2f050 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2f060 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f070 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2f080 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2f090 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2f0a0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2f0b0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2f0c0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2f0d0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2f0e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2f0f0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2f100 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2f110 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2f120 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2f130 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2f140 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2f150 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2f160 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2f170 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2f180 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2f190 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2f1a0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2f1b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f1c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2f1d0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2f1e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2f1f0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2f200 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2f210 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2f220 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2f230 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2f240 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2f250 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2f260 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2f270 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2f280 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2f290 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2f2a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2f2b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2f2c0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2f2d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f2e0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2f2f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f300 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2f310 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2f320 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f330 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2f340 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2f350 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2f360 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2f370 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2f380 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2f390 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2f3a0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2f3b0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2f3c0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2f3d0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2f3e0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2f3f0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2f400 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2f410 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2f420 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2f430 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2f440 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2f450 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2f460 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2f470 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2f480 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2f490 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2f4a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2f4b0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2f4c0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2f4d0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2f4e0 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2f4f0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2f500 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2f510 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2f520 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2f530 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2f540 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2f550 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2f560 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2f570 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2f580 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2f590 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2f5a0 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2f5b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2f5c0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2f5d0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2f5e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2f5f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2f600 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2f610 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2f620 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2f630 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2f640 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2f650 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2f660 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2f670 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2f680 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2f690 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2f6a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2f6b0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2f6c0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2f6d0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2f6e0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2f6f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2f700 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2f710 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2f720 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2f730 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2f740 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2f750 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2f760 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2f770 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2f780 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2f790 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2f7a0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2f7b0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2f7c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2f7d0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2f7e0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2f7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f800 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2f810 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2f820 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2f830 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2f840 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2f850 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2f860 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2f870 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2f880 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2f890 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2f8a0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2f8b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2f8c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2f8d0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2f8e0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2f8f0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2f900 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2f910 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2f920 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2f930 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2f940 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2f950 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2f960 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2f970 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2f980 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2f990 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2f9a0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2f9b0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2f9c0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2f9d0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2f9e0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2f9f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2fa00 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2fa10 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2fa20 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2fa30 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2fa40 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2fa50 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2fa60 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2fa70 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2fa80 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54  _pointer(S,I,P,T
2fa90 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73  ,D) routine caus
2faa0 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61  es the I-th para
2fab0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65  meter in.** [pre
2fac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fad0 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51   S to have an SQ
2fae0 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c  L value of NULL,
2faf0 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a   but to also be.
2fb00 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
2fb10 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50  th the pointer P
2fb20 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20   of type T.  ^D 
2fb30 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
2fb40 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61   pointer or.** a
2fb50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
2fb60 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
2fb70 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65  n for P. ^SQLite
2fb80 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2fb90 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44  .** destructor D
2fba0 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61   with a single a
2fbb0 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65  rgument of P whe
2fbc0 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64  n it is finished
2fbd0 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68   using.** P.  Th
2fbe0 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68  e T parameter sh
2fbf0 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63  ould be a static
2fc00 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61   string, prefera
2fc10 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20  bly a string.** 
2fc20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c  literal. The sql
2fc30 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
2fc40 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70  r() routine is p
2fc50 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  art of the.** [p
2fc60 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69  ointer passing i
2fc70 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20  nterface] added 
2fc80 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e  for SQLite 3.20.
2fc90 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  0..**.** ^If any
2fca0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2fcb0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2fcc0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2fcd0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2fce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2fcf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd00 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2fd10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2fd20 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2fd30 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2fd40 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2fd50 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2fd60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2fd70 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2fd80 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2fd90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2fda0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2fdb0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2fdc0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2fdd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fde0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2fdf0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2fe00 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2fe10 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2fe20 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2fe30 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2fe40 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2fe50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2fe60 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2fe70 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2fe80 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2fe90 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2fea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2feb0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2fec0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2fed0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2fee0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2fef0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2ff00 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2ff10 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2ff20 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2ff30 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2ff40 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2ff50 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2ff60 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2ff70 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2ff80 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2ff90 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2ffa0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2ffb0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2ffc0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2ffd0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2ffe0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2fff0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
30000 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
30010 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
30020 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
30030 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30050 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
30060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30070 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30080 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
30090 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
300a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
300b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
300c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
300d0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
300e0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
300f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30110 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
30120 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
30130 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
30140 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
30150 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
30160 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30170 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
30180 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
30190 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
301a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
301b0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
301c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
301d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
301e0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
301f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
30200 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
30210 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
30220 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
30230 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
30240 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
30250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
30260 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
30270 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30290 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
302a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
302b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
302c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
302d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
302e0 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
302f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30300 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
30310 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
30320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30330 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
30340 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
30350 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
30360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30370 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30380 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
30390 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
303a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
303b0 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74  inter(sqlite3_st
303c0 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c  mt*, int, void*,
303d0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69   const char*,voi
303e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
303f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
30400 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
30410 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
30420 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
30430 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
30440 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30450 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
30460 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
30470 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
30480 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
30490 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
304a0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
304b0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
304c0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
304d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
304e0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
304f0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
30500 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
30510 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
30520 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
30530 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
30540 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
30550 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
30560 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
30570 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
30580 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
30590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
305a0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
305b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
305c0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
305d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
305e0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
305f0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
30600 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
30610 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
30620 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
30630 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
30640 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
30650 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
30660 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
30670 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
30680 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
30690 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
306a0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
306b0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
306c0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
306d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
306e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
306f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
30700 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
30710 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
30720 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
30730 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30740 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
30750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
30760 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
30770 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
30780 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30790 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
307a0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
307b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
307c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
307d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
307e0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
307f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30800 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
30810 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
30820 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
30830 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30840 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
30850 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
30860 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
30870 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
30880 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
30890 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
308a0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
308b0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
308c0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
308d0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
308e0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
308f0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
30900 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
30910 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
30920 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
30930 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
30940 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
30950 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
30960 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
30970 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
30980 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
30990 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
309a0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
309b0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
309c0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
309d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
309e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
309f0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
30a00 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
30a10 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
30a20 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
30a30 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
30a40 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
30a50 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
30a60 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
30a70 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
30a80 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
30a90 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
30aa0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
30ab0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
30ac0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
30ad0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
30ae0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
30af0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
30b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
30b10 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
30b20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30b30 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
30b40 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
30b50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
30b60 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
30b70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30b80 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
30b90 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
30ba0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30bb0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
30bc0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
30bd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30be0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
30bf0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
30c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
30c10 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
30c20 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
30c30 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
30c40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30c50 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
30c60 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
30c70 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
30c80 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
30c90 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
30ca0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
30cb0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
30cc0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
30cd0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
30ce0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30cf0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
30d00 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
30d10 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
30d20 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
30d30 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
30d40 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
30d50 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
30d60 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
30d70 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
30d80 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
30d90 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
30da0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
30db0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30dc0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
30dd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
30de0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
30df0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
30e00 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30e10 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
30e20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30e30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
30e40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
30e50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30e60 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
30e70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30e80 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
30e90 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
30ea0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
30eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30ec0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
30ed0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
30ee0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
30ef0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30f00 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
30f10 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
30f20 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
30f30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
30f40 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
30f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
30f60 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
30f70 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
30f80 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
30f90 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
30fa0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
30fb0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
30fc0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
30fd0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
30fe0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30ff0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
31000 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
31010 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
31020 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
31030 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31040 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
31050 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
31060 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
31070 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
31080 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
31090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
310a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
310b0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
310c0 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
310d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
310e0 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
310f0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
31100 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
31110 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
31120 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
31130 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
31140 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
31150 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
31160 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
31170 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
31180 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
31190 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
311a0 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
311b0 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
311c0 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
311d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
311e0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
311f0 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
31200 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
31210 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
31220 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
31230 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
31240 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
31250 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31260 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
31270 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
31280 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31290 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
312a0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
312b0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
312c0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
312d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
312e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
312f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
31300 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
31310 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
31320 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
31330 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
31340 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
31350 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
31360 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
31370 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31380 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
31390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
313a0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
313b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
313c0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
313d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
313e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
313f0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
31400 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
31410 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31420 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31430 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
31440 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
31450 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
31460 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
31470 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
31480 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
31490 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
314a0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
314b0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
314c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
314d0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
314e0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
314f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31500 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
31510 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
31520 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
31530 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
31540 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
31550 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
31560 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
31570 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31580 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
31590 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
315a0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
315b0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
315c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
315d0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
315e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
315f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
31600 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
31610 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
31620 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
31630 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
31640 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
31650 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
31660 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
31670 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
31680 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
31690 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
316a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
316b0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
316c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
316d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
316e0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
316f0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
31700 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
31710 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
31720 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
31730 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
31740 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
31750 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
31760 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
31770 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
31780 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
31790 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
317a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
317b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
317c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
317d0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
317e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
317f0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
31800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
31810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31820 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
31830 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
31840 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
31850 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31860 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31870 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
31880 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
31890 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
318a0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
318b0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
318c0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
318d0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
318e0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
318f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
31900 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
31910 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
31920 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
31930 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
31940 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
31950 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
31960 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
31970 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
31980 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
31990 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
319a0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
319b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
319c0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
319d0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
319e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
319f0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
31a00 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
31a10 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
31a20 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
31a30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31a40 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
31a50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
31a60 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
31a70 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
31a80 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
31a90 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
31aa0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
31ab0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31ac0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
31ad0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
31ae0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
31af0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
31b00 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
31b10 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
31b20 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
31b30 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
31b40 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
31b50 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
31b60 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
31b70 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
31b80 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
31b90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31ba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
31bb0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
31bc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31bd0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
31be0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
31bf0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
31c00 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
31c10 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
31c20 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
31c30 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
31c40 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
31c50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
31c60 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
31c70 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
31c80 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
31c90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
31ca0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
31cb0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
31cc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31cd0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
31ce0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
31cf0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
31d00 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
31d10 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
31d20 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
31d30 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
31d40 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
31d50 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
31d60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31d70 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
31d80 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
31d90 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
31da0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
31db0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
31dc0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
31dd0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
31de0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
31df0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
31e00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
31e10 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
31e20 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
31e30 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
31e40 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
31e50 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
31e60 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
31e70 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
31e80 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
31e90 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
31ea0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
31eb0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
31ec0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
31ed0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
31ee0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
31ef0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
31f00 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
31f10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
31f20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
31f30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
31f40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31f50 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
31f60 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
31f70 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
31f80 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
31f90 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
31fa0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
31fb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
31fc0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
31fd0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
31fe0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
31ff0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32000 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
32010 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
32020 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
32030 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
32040 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
32050 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
32060 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
32070 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
32080 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
32090 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
320a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
320b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
320c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
320d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
320e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
320f0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
32100 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
32110 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
32130 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
32140 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
32150 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
32160 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
32170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32180 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
32190 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
321a0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
321b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
321c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
321d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
321e0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
321f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
32200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32210 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
32220 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
32230 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
32240 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32250 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
32260 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
32270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
32280 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
32290 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
322a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
322b0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
322c0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
322d0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
322e0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
322f0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
32300 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
32310 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
32320 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
32330 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
32340 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
32350 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
32360 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
32370 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
32380 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
32390 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
323a0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
323b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
323c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
323d0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
323e0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
323f0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
32400 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
32410 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
32420 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
32430 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
32440 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
32450 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
32460 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
32470 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
32480 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
32490 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
324a0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
324b0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
324c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
324d0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
324e0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
324f0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
32500 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
32510 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
32520 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
32530 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
32540 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
32550 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
32560 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
32570 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
32580 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
32590 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
325a0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
325b0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
325c0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
325d0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
325e0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
325f0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
32600 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
32610 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
32620 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
32630 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
32640 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
32650 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
32660 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
32670 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
32680 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
32690 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
326a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
326b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
326c0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
326d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
326e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
326f0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
32700 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
32710 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
32720 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
32730 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
32740 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
32750 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32760 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
32770 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
32780 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
32790 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b  sing any of.** [
327a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
327b0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
327c0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
327d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
327e0 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  6_v2()],.** or [
327f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32800 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v3()] or one o
32810 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
32820 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
32830 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
32840 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
32850 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
32860 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
32870 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
32880 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
32890 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
328a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
328b0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
328c0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
328d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
328e0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
328f0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
32900 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
32910 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
32920 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74  e newer "vX" int
32930 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69  erfaces.** [sqli
32940 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
32950 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32960 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
32970 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32980 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
32990 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
329a0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
329b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
329c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
329d0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
329e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
329f0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
32a00 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e  e.** new "vX" in
32a10 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
32a20 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
32a30 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
32a40 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
32a50 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
32a60 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
32a70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
32a80 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
32a90 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
32aa0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
32ab0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
32ac0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
32ad0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
32ae0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
32af0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
32b00 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
32b10 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
32b20 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
32b30 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
32b40 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
32b50 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
32b60 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
32b70 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
32b80 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
32b90 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
32ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
32bb0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
32bc0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
32bd0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
32be0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
32bf0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
32c00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
32c10 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
32c20 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
32c30 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
32c40 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
32c50 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
32c60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
32c70 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
32c80 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
32c90 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
32ca0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
32cb0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
32cc0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
32cd0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
32ce0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
32cf0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
32d00 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
32d10 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
32d20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
32d30 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
32d40 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
32d50 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
32d60 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
32d70 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
32d80 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
32d90 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
32da0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
32db0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32dc0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
32dd0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
32de0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
32df0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
32e00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
32e10 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
32e20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
32e30 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
32e40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
32e50 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
32e60 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
32e70 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
32e80 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
32e90 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
32ea0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
32eb0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
32ec0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
32ed0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
32ee0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
32ef0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
32f00 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
32f10 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
32f20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
32f30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
32f40 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
32f50 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
32f60 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
32f70 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
32f80 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
32f90 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
32fa0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
32fb0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
32fc0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
32fd0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
32fe0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
32ff0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
33000 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
33010 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
33020 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
33030 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
33040 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
33050 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
33060 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
33070 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
33080 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
33090 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
330a0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
330b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
330c0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
330d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
330e0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
330f0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
33100 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
33110 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
33120 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
33130 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
33140 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
33150 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
33160 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
33170 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
33180 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
33190 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
331a0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
331b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
331c0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
331d0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
331e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
331f0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
33200 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
33210 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
33220 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
33230 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
33240 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
33250 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
33260 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
33270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33280 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
33290 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
332a0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
332b0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
332c0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
332d0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
332e0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
332f0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
33300 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
33310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
33320 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
33330 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
33340 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
33350 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
33360 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
33370 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
33380 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
33390 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
333a0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
333b0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
333c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
333d0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
333e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
333f0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
33400 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
33410 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
33420 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
33430 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65  .  But after [ve
33440 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20  rsion 3.6.23.1] 
33450 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e  ([dateof:3.6.23.
33460 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  1],.** sqlite3_s
33470 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
33480 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
33490 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
334a0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
334b0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
334c0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
334d0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
334e0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
334f0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
33500 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
33510 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
33520 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
33530 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
33540 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
33550 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
33560 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
33570 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
33580 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
33590 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
335a0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
335b0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
335c0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
335d0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
335e0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
335f0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
33600 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
33610 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
33620 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
33630 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
33640 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
33650 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
33660 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
33670 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
33680 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
33690 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
336a0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
336b0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
336c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
336d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
336e0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
336f0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
33700 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
33710 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
33720 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
33730 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
33740 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
33750 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
33760 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
33770 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
33780 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
33790 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
337a0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
337b0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
337c0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ents.** using [s
337d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
337e0 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  3()] or [sqlite3
337f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
33800 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
33810 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
33820 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33830 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61  e16_v3()] instea
33840 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
33850 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
33860 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
33870 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
33880 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
33890 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
338a0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
338b0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
338c0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
338d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
338e0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
338f0 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
33900 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
33910 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33920 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
33930 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
33940 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
33950 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
33960 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
33970 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33990 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
339a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
339b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
339c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
339d0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
339e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
339f0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
33a00 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
33a10 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
33a20 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
33a30 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
33a40 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
33a50 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
33a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
33a70 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
33a80 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
33a90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
33aa0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
33ab0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
33ac0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
33ad0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33ae0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
33af0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
33b00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33b10 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33b20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33b30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33b40 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
33b50 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
33b60 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
33b70 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
33b80 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
33b90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33ba0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
33bb0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
33bc0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
33bd0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
33be0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
33bf0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
33c00 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
33c10 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
33c20 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
33c30 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
33c40 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
33c50 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
33c60 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
33c70 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
33c80 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
33c90 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
33ca0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
33cb0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
33cc0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
33cd0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
33ce0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33cf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d00 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
33d10 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
33d20 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
33d30 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
33d40 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
33d50 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
33d60 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
33d70 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
33d80 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
33d90 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
33da0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
33db0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
33dc0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
33dd0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
33de0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
33df0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
33e00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33e10 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
33e20 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
33e30 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
33e40 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
33e50 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
33e60 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
33e70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
33e80 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
33e90 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
33ea0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
33eb0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
33ec0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
33ed0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
33ee0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
33ef0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
33f00 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
33f10 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
33f20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33f30 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
33f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
33f50 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
33f60 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
33f70 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
33f80 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
33f90 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
33fa0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
33fb0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
33fc0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
33fd0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
33fe0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
33ff0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
34000 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
34010 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
34020 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
34030 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
34040 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
34050 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
34060 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72  .**.** <b>Summar
34070 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b  y:</b>.** <block
34080 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72  quote><table bor
34090 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e  der=0 cellpaddin
340a0 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d  g=0 cellspacing=
340b0 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  0>.** <tr><td><b
340c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
340d0 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  blob</b><td>&rar
340e0 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c  r;<td>BLOB resul
340f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
34110 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  ouble</b><td>&ra
34120 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75  rr;<td>REAL resu
34130 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34140 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34150 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  int</b><td>&rarr
34160 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45  ;<td>32-bit INTE
34170 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
34180 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34190 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62  _column_int64</b
341a0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36  ><td>&rarr;<td>6
341b0 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  4-bit INTEGER re
341c0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
341d0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
341e0 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72  n_text</b><td>&r
341f0 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45  arr;<td>UTF-8 TE
34200 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
34210 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34220 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62  column_text16</b
34230 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
34240 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c  TF-16 TEXT resul
34250 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
34270 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  alue</b><td>&rar
34280 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74  r;<td>The result
34290 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69   as an .** [sqli
342a0 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74  te3_value|unprot
342b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
342c0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  lue] object..** 
342d0 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  <tr><td>&nbsp;<t
342e0 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
342f0 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  p;.** <tr><td><b
34300 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34310 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61  bytes</b><td>&ra
34320 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61  rr;<td>Size of a
34330 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54   BLOB.** or a UT
34340 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20  F-8 TEXT result 
34350 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
34360 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34370 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62  olumn_bytes16&nb
34380 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a  sp;&nbsp;</b>.**
34390 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70   <td>&rarr;&nbsp
343a0 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20  ;&nbsp;<td>Size 
343b0 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58  of UTF-16.** TEX
343c0 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  T in bytes.** <t
343d0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
343e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e  _column_type</b>
343f0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65  <td>&rarr;<td>De
34400 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70  fault.** datatyp
34410 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a  e of the result.
34420 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f  ** </table></blo
34430 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c  ckquote>.**.** <
34440 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a  b>Details:</b>.*
34450 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
34460 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
34470 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
34480 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
34490 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
344a0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
344b0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
344c0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
344d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
344e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
344f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34500 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
34510 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
34520 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
34530 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
34540 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
34550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
34560 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
34570 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
34580 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
34590 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
345a0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
345b0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
345c0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
345d0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
345e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
345f0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
34600 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
34610 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
34620 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
34630 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
34640 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
34650 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34660 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
34670 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
34680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
34690 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
346a0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
346b0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
346c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
346d0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
346e0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
346f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
34700 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
34710 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
34720 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
34730 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
34740 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34750 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
34760 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
34770 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
34780 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
34790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
347a0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
347b0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
347c0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
347d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
347e0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
347f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
34800 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
34810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
34820 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
34830 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
34840 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
34850 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
34860 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
34870 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34880 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
34890 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
348a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
348b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
348c0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
348d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
348e0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
348f0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
34900 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
34910 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
34920 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
34930 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
34940 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78  ** The first six
34950 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c   interfaces (_bl
34960 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e  ob, _double, _in
34970 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74  t, _int64, _text
34980 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a  , and _text16).*
34990 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68  * each return th
349a0 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73  e value of a res
349b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20  ult column in a 
349c0 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f  specific data fo
349d0 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65  rmat.  If.** the
349e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
349f0 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20  s not initially 
34a00 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64  in the requested
34a10 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61   format (for exa
34a20 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20  mple,.** if the 
34a30 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e  query returns an
34a40 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65   integer but the
34a50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34a60 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65  text() interface
34a70 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65  .** is used to e
34a80 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65  xtract the value
34a90 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61  ) then an automa
34aa0 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
34ab0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
34ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34ae0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
34af0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
34b00 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
34b10 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
34b20 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
34b30 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
34b40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
34b50 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
34b60 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
34b70 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
34b80 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
34b90 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
34ba0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
34bb0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
34bc0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20  ..** The return 
34bd0 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33  value of sqlite3
34be0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63  _column_type() c
34bf0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
34c00 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66  cide which.** of
34c10 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69   the first six i
34c20 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
34c30 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  be used to extra
34c40 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61  ct the column va
34c50 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  lue..** The valu
34c60 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
34c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34c80 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
34c90 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20  ingful if no.** 
34ca0 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
34cb0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
34cc0 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65  occurred for the
34cd0 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69   value in questi
34ce0 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61  on.  .** After a
34cf0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
34d00 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
34d10 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
34d20 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34d30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74   is undefined, t
34d40 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20  hough harmless. 
34d50 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
34d60 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
34d70 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
34d80 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
34d90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
34da0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
34db0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
34dc0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
34dd0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
34de0 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74  a TEXT string, t
34df0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
34e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
34e10 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
34e20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e  umn_bytes16() in
34e30 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20  terfaces can be 
34e40 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e  used to determin
34e50 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66  e the size.** of
34e60 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
34e70 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
34e80 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34e90 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
34ea0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
34eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34ec0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
34ed0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
34ee0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
34ef0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34f00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34f10 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
34f20 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
34f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34f40 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
34f50 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
34f60 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
34f70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34f80 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
34f90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34fa0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
34fb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
34fc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
34fd0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
34fe0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
34ff0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
35000 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
35010 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
35020 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
35030 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
35040 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
35050 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
35060 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
35070 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
35080 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
35090 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
350a0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
350b0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
350c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
350d0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
350e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
350f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35100 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
35110 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
35120 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35130 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
35140 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
35150 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
35160 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
35170 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
35180 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
35190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
351a0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
351b0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
351c0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
351d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
351e0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
351f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
35200 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
35210 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
35220 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
35230 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
35240 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35250 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
35260 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35270 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
35280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35290 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
352a0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
352b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
352c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
352d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
352e0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
352f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35300 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
35310 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
35320 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
35330 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
35340 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
35350 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
35360 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
35370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35380 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
35390 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
353a0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
353b0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
353c0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
353d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
353e0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
353f0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
35400 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
35410 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
35420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35430 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
35440 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
35450 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
35460 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
35470 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
35480 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
35490 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
354a0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
354b0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
354c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
354d0 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
354e0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
354f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
35500 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
35510 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
35520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35530 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
35540 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
35550 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
35560 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
35570 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
35580 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
35590 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
355a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
355b0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
355c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
355d0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
355e0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
355f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35600 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
35610 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
35620 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
35630 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
35640 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
35650 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
35660 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
35670 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
35680 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
35690 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
356a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
356b0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
356c0 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
356d0 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e  readsafe..** Hen
356e0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
356f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69  column_value() i
35700 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e  nterface.** is n
35710 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65  ormally only use
35720 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69  ful within the i
35730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
35740 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f   .** [applicatio
35750 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
35760 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72  nctions] or [vir
35770 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f  tual tables], no
35780 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d  t within.** top-
35790 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f  level applicatio
357a0 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n code..**.** Th
357b0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
357c0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
357d0 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61  convert the data
357e0 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
357f0 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d  lt..** ^For exam
35800 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
35810 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
35820 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
35830 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
35840 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
35850 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
35860 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
35870 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
35880 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
35890 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
358a0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
358b0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
358c0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
358d0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
358e0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
358f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
35900 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
35910 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
35920 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
35930 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
35940 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
35950 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
35960 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35970 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35980 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
35990 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
359a0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
359b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
359c0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
359d0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
359e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
359f0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
35a00 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
35a10 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
35a20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35a30 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
35a40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
35a50 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
35a60 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35a70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
35a80 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
35a90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
35aa0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
35ab0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
35ac0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
35ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
35ae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35af0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35b00 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
35b10 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
35b20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35b30 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35b40 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
35b50 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
35b60 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
35b70 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
35b80 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
35b90 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
35ba0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
35bb0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35bc0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
35bd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
35be0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
35bf0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35c00 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35c10 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35c20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35c30 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
35c40 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
35c50 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
35c60 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
35c70 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
35c80 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
35c90 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35ca0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35cb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35cc0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
35cd0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
35ce0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
35cf0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35d00 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35d10 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
35d20 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
35d30 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
35d40 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
35d50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
35d60 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
35d70 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
35d80 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
35d90 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
35da0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
35db0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
35dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35dd0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
35de0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35df0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
35e00 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
35e10 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
35e20 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
35e30 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
35e40 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
35e50 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
35e60 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
35e70 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
35e80 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
35e90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
35ea0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
35eb0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
35ec0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
35ed0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
35ee0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
35ef0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
35f00 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
35f10 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
35f20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35f30 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
35f40 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
35f50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35f60 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
35f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35f80 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
35f90 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
35fa0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
35fb0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
35fc0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
35fd0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
35fe0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
35ff0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
36000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
36010 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
36020 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
36030 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
36040 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
36050 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
36060 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
36070 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
36080 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
36090 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
360a0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
360b0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
360c0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
360d0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
360e0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
360f0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
36100 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
36110 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
36120 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
36130 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
36140 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
36150 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
36160 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
36170 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
36180 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
36190 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
361a0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
361b0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
361c0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
361d0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
361e0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
361f0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
36200 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
36210 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
36220 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
36230 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
36240 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
36250 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
36260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36270 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
36280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36290 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
362a0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
362b0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
362c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
362d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
362e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
362f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36300 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36320 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
36330 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
36340 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
36350 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
36360 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
36370 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
36380 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
36390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
363a0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
363b0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
363c0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
363d0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
363e0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
363f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
36400 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
36410 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
36420 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
36430 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
36440 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
36450 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
36460 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
36470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36480 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
36490 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
364a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
364b0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
364c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
364d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
364e0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
364f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
36500 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
36510 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
36520 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
36530 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
36540 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
36550 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
36560 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
36570 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36580 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
36590 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
365a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
365b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
365c0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
365d0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
365e0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
365f0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
36600 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74  tically.  Do not
36610 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
36620 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
36630 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
36640 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
36650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36660 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
36670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
36680 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
36690 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
366a0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
366b0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
366c0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
366d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
366e0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
366f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
36700 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
36710 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
36720 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
36730 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
36740 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
36750 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
36760 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
36770 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
36780 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
36790 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
367a0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
367b0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
367c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
367d0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
367e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
367f0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
36800 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
36810 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36830 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
36840 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36850 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
36860 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
36870 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
36880 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36890 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
368a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
368b0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
368c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
368d0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
368e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
368f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
36900 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
36920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
36930 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
36940 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
36950 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
36960 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
36970 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36980 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
36990 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
369a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
369b0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
369c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
369d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
369e0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
369f0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
36a00 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
36a10 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
36a20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
36a30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
36a40 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
36a50 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
36a60 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
36a70 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
36a80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
36a90 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36aa0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
36ab0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
36ac0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
36ad0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
36ae0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
36af0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
36b00 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
36b10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
36b20 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
36b30 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
36b40 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
36b50 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
36b60 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
36b70 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
36b80 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
36b90 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
36ba0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
36bb0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
36bc0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
36bd0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36be0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
36bf0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
36c00 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
36c10 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
36c20 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
36c30 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
36c40 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
36c50 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
36c60 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
36c70 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
36c80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
36c90 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
36ca0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
36cb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36cc0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
36cd0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
36ce0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
36cf0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
36d00 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
36d10 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
36d20 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
36d30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
36d40 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
36d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
36d60 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
36d70 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
36d80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36d90 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
36da0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
36db0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
36dc0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
36dd0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
36de0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
36df0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
36e00 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36e10 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36e20 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
36e30 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
36e40 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
36e50 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
36e60 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
36e70 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
36e80 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
36e90 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
36ea0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
36eb0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
36ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
36ed0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
36ee0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36ef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
36f00 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
36f10 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
36f20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36f30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
36f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
36f50 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
36f60 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
36f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36f80 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
36f90 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
36fa0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
36fb0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
36fc0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
36fd0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
36fe0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
36ff0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
37000 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
37010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
37020 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
37030 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
37040 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
37050 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
37060 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
37070 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
37080 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
37090 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
370a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
370b0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
370c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
370d0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
370e0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
370f0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
37100 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
37110 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
37120 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
37130 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
37140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
37150 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
37160 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
37170 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
37180 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
37190 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
371a0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
371b0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
371c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
371d0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
371e0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
371f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
37200 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37210 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
37220 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
37230 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
37240 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
37250 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
37260 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
37270 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
37280 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
37290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
372a0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
372b0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
372c0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
372d0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
372e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
372f0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
37300 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
37310 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
37320 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
37330 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
37340 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
37350 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
37360 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
37370 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
37380 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
37390 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
373a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
373b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
373c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
373d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
373e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
373f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
37400 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
37410 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
37420 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
37430 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
37440 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
37450 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
37460 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
37470 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
37480 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
37490 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
374a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
374b0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
374c0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
374d0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
374e0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
374f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
37500 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
37510 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
37520 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
37530 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
37540 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
37550 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
37560 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
37570 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
37580 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
37590 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
375a0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
375b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
375c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
375d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
375e0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
375f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37600 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
37610 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
37620 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
37630 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
37640 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
37650 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
37660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
37670 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37680 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
37690 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
376a0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
376b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
376c0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
376d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
376e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
376f0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
37700 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
37710 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
37720 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
37730 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
37740 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
37750 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
37760 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
37770 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
37780 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
37790 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
377a0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
377b0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
377c0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
377d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
377e0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
377f0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
37800 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
37810 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
37820 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
37830 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
37840 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
37850 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
37860 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
37870 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
37880 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
37890 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
378a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
378b0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
378c0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
378d0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
378e0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
378f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
37900 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
37910 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
37920 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
37930 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
37940 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
37950 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
37960 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
37970 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
37980 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
37990 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
379a0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
379b0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
379c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
379d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
379e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
379f0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
37a00 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
37a10 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
37a20 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
37a30 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
37a40 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
37a50 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
37a60 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
37a70 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
37a80 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
37a90 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
37aa0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
37ab0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
37ac0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
37ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
37ae0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
37af0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
37b00 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
37b10 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
37b20 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
37b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37b40 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
37b50 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
37b60 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
37b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37b80 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
37b90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
37ba0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
37bb0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
37bc0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37bd0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
37be0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
37bf0 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
37c00 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
37c10 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
37c20 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
37c30 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
37c40 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
37c50 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
37c60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
37c70 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
37c80 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
37c90 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
37ca0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
37cb0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
37cc0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
37cd0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
37ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37cf0 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
37d00 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
37d10 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
37d20 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
37d30 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
37d40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
37d50 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
37d60 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
37d70 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
37d80 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
37d90 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
37da0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
37db0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
37dc0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
37dd0 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
37de0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
37df0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
37e00 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
37e10 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
37e20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
37e30 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
37e40 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
37e50 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
37e60 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
37e70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
37e80 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
37e90 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
37ea0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
37eb0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
37ec0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
37ed0 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
37ee0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
37ef0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
37f00 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
37f10 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
37f20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37f30 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
37f40 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
37f50 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
37f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
37f70 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
37f80 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
37f90 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
37fa0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
37fb0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
37fc0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
37fd0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
37fe0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
37ff0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
38000 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
38010 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
38020 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
38030 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38040 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
38050 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
38060 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
38070 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
38080 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
38090 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
380a0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
380b0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
380c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
380d0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
380e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
380f0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
38100 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
38110 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
38120 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
38130 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
38140 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
38150 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
38160 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
38170 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
38180 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
38190 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
381a0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
381b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
381c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
381d0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
381e0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
381f0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
38200 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
38210 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
38220 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
38230 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
38240 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
38250 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
38260 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
38270 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
38280 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
38290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
382a0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
382b0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
382c0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
382d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
382e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
382f0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
38300 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
38310 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
38320 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
38330 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
38340 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
38350 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
38360 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
38370 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
38380 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
38390 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
383a0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
383b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
383c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
383d0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
383e0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
383f0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
38400 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
38410 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
38420 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
38430 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
38440 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
38450 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
38460 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
38470 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
38480 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
38490 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
384a0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
384b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
384c0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
384d0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
384e0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
384f0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
38500 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
38510 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
38520 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
38530 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
38540 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
38550 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
38560 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
38570 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
38580 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
38590 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
385a0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
385b0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
385c0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
385d0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
385e0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
385f0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
38600 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
38610 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
38620 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
38630 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
38640 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
38650 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
38660 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
38670 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
38680 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
38690 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
386a0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
386b0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
386c0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
386d0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
386e0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
386f0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
38700 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
38710 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38720 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
38730 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
38740 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
38750 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
38760 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
38770 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
38780 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
38790 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls m