/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 38390767acc1914d58930e03149595ee4710afa4e3c43ab6c3a8aea3f1a6b8cd:


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 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7b0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
f7c0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
f7d0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
f7e0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
f7f0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
f800: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
f810: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
f820: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
f830: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
f840: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
f850: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
f860: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
f870: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
f880: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
f890: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
f8a0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
f8b0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
f8c0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f8d0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
f8e0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
f8f0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
f900: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
f910: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
f920: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
f930: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
f940: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
f950: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
f960: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
f970: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
f980: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
f990: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
f9a0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
f9b0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
f9c0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
f9d0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
f9e0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
f9f0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
fa00: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
fa10: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
fa20: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
fa30: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
fa40: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
fa50: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
fa60: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
fa70: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
fa80: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
fa90: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
faa0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
fab0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
fac0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
fad0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
fae0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
faf0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
fb00: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
fb10: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
fb20: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
fb30: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
fb40: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
fb50: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
fb60: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
fb70: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
fb80: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
fb90: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
fba0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
fbb0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
fbc0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
fbd0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
fbe0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
fbf0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fc00: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
fc10: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
fc20: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
fc30: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
fc40: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
fc50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
fc60: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
fc70: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
fc80: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
fc90: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
fca0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fcb0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
fcc0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
fcd0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
fce0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
fcf0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
fd00: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
fd10: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
fd20: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
fd30: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
fd40: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
fd50: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
fd60: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
fd70: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
fd80: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
fd90: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
fda0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
fdb0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
fdc0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
fdd0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
fde0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
fdf0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
fe00: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
fe10: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
fe20: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
fe30: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
fe40: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
fe50: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
fe60: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
fe70: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
fe80: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
fe90: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
fea0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
feb0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
fec0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
fed0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
fee0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
fef0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
ff00: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
ff10: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
ff20: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
ff30: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
ff40: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
ff50: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
ff60: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
ff70: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
ff80: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
ff90: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
ffa0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
ffb0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
ffc0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
ffd0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
ffe0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
fff0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
10000 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
10010 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
10020 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
10030 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
10040 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
10050 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
10060 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
10070 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
10080 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
10090 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
100a0 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
100b0 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
100c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
100d0 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
100e0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
100f0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
10100 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
10110 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
10120 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
10130 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
10140 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
10150 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
10160 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
10170 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
10180 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
10190 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
101a0 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
101b0 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
101c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
101d0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
101e0 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
101f0 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
10200 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
10210 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
10220 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10230 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
10240 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
10250 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
10260 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
10280 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
10290 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
102a0 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
102b0 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
102c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
102d0 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
102e0 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
102f0 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
10300 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
10310 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
10320 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10330 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10340 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
10350 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
10360 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10370 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10380 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10390 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
103a0 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
103b0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
103c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
103d0 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
103e0 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
103f0 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
10400 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10410 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
10420 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
10430 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
10440 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10450 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
10460 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
10470 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
10480 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
10490 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
104a0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
104b0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
104c0 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
104d0 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
104e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
104f0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
10500 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
10510 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
10520 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
10530 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
10540 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
10550 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
10560 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
10570 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
10590 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
105a0 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
105b0 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
105c0 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
105d0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
105e0 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
105f0 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
10600 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
10610 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
10620 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
10630 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10640 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
10650 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
10660 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10670 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10680 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10690 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
106a0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
106b0 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
106c0 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
106d0 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
106e0 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
106f0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
10700 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
10720 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10730 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
10740 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
10750 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10760 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10770 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10780 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
10790 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
107a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
107b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
107c0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
107d0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
107e0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
107f0 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
10800 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10810 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
10820 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10830 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
10840 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10850 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10860 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10870 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10880 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
108a0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
108b0 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
108d0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
108e0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
108f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10900 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10910 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10920 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10930 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10940 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10950 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10960 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10970 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10980 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10990 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
109a0 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
109b0 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
109c0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
109d0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
109e0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
109f0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10a00 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10a10 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10a20 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10a30 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10a40 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10a50 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10a60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10a70 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10a80 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10a90 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10aa0 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10ab0 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10ac0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10ad0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10ae0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10af0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10b00 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10b10 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
10b20 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10b30 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10b40 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
10b50 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
10b60 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10b70 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10b80 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10b90 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
10ba0 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
10bb0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10bc0 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
10bd0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
10be0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
10bf0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
10c00 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
10c10 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
10c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10c30 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
10c40 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
10c50 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10c60 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
10c70 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
10c80 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10ca0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10cb0 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10cc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10cd0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10ce0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10cf0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10d00 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10d10 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10d20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10d30 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10d40 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
10d50 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
10d60 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10d70 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
10d80 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
10d90 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
10da0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10db0 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10dc0 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10dd0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10de0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10df0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10e00 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10e10 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10e20 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10e30 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10e40 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
10e50 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10e60 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10e70 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10e80 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
10e90 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
10ea0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10eb0 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10ec0 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10ed0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10ee0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10ef0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10f00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10f10 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10f20 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10f30 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10f40 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
10f50 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
10f60 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
10f70 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
10f80 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
10f90 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
10fa0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10fb0 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10fc0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10fd0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10fe0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10ff0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
11000 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11010 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
11020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11030 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
11040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11050 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
11060 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
11070 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11080 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
11090 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
110a0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
110b0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
110c0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
110d0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
110e0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
110f0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
11100 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
11110 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
11120 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
11130 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
11140 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
11150 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
11160 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
11170 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
11180 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
11190 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
111a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
111b0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
111c0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
111d0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
111e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
111f0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
11200 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
11210 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
11220 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
11230 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
11240 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
11250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11260 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
11270 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
11280 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
11290 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
112a0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
112b0 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
112c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
112d0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
112e0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
112f0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
11300 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
11310 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
11320 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
11330 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
11340 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
11350 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
11360 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
11370 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11380 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
11390 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
113a0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
113b0 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
113c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
113d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
113e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
113f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
11400 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11410 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
11420 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11430 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
11440 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
11450 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
11460 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
11470 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
11480 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11490 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
114a0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
114b0 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
114c0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
114d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
114e0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
114f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
11500 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
11510 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11520 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
11530 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
11540 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11550 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
11560 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
11570 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
11580 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
11590 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
115a0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
115b0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
115c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
115d0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
115e0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
115f0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
11600 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
11610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
11620 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
11630 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
11640 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
11650 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11660 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
11670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11680 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
11690 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
116a0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
116b0 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
116c0 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
116d0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
116e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
116f0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
11700 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
11710 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
11720 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
11730 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11740 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
11750 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
11760 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
11770 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11790 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
117a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
117b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
117c0 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
117d0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
117e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
117f0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
11800 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
11810 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
11820 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11830 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11840 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11850 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11860 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11870 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11880 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11890 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
118a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
118b0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
118c0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
118d0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
118e0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
118f0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
11900 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11910 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11920 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11930 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11940 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11950 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11970 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11980 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11990 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
119a0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
119b0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
119c0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
119d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
119e0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
119f0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
11a00 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11a10 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11a20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11a30 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11a40 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11a50 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11a60 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11a70 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11a80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11a90 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11aa0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11ac0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11ad0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11ae0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11af0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11b00 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11b10 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
11b20 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11b30 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11b40 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
11b50 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
11b60 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
11b70 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
11b80 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
11b90 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11ba0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11bb0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
11bc0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
11bd0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
11be0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11bf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
11c00 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
11c10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11c20 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11c30 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
11c40 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
11c50 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
11c60 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
11c70 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
11c80 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
11c90 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11ca0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11cb0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11cc0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11cd0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11ce0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11cf0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11d00 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11d10 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11d20 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11d30 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11d40 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
11d50 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
11d60 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
11d70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
11d80 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
11d90 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
11da0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11db0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11dc0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11dd0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11de0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11df0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11e00 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11e20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11e30 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
11e50 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
11e60 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
11e70 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
11e80 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
11e90 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
11ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11eb0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11ed0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11ef0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11f00 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11f10 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11f20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11f30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11f40 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
11f50 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
11f60 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
11f70 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
11f80 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
11f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
11fa0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11fb0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11fc0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11fd0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11fe0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11ff0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
12000 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
12010 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
12020 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
12030 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
12040 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
12050 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
12060 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
12070 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
12080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12090 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
120a0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
120b0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
120c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
120d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
120e0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
120f0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
12100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12110 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12120 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
12130 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
12140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12150 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
12160 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
12170 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
12180 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
12190 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
121a0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
121b0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
121c0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
121d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
121e0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
121f0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
12200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12210 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12220 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12230 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12240 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12250 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12260 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
12270 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12280 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
12290 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
122a0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
122b0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
122c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
122d0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
122e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
122f0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
12300 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
12310 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
12320 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
12330 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
12340 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
12350 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
12360 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
12370 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
12380 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
12390 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
123a0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
123b0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
123c0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
123d0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
123e0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
123f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12400 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
12410 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
12420 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
12430 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
12440 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
12450 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12460 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
12470 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
12480 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
12490 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
124a0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
124b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
124c0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
124d0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
124e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
124f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
12500 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
12510 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
12520 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
12530 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
12540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12550 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
12560 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
12570 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
12580 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
12590 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
125a0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
125b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
125c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
125d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
125e0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
125f0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
12600 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12610 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
12620 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
12630 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
12640 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
12650 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
12660 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
12670 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
12680 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
12690 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
126a0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
126b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
126e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
126f0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
12700 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12710 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
12720 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
12730 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
12740 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
12750 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
12760 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
12770 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
12780 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
12790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
127a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
127b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
127c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
127d0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
127e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
127f0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
12800 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
12810 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
12820 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12830 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12840 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12850 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12860 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12870 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12880 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12890 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
128a0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
128b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
128c0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
128d0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
128e0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
128f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12900 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12920 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12930 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12940 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12950 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12960 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12970 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12980 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12990 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
129a0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
129b0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
129c0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
129d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129e0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
129f0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
12a00 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12a10 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12a20 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12a30 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12a40 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12a50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12a60 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12a70 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12a80 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12a90 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
12aa0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
12ab0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12ac0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
12ad0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
12ae0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
12af0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
12b00 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
12b10 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12b20 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
12b30 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
12b40 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
12b50 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12b70 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
12b80 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
12b90 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
12ba0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12bb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12bd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12be0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
12bf0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
12c00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12c10 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
12c20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12c30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12c40 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
12c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12c60 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
12c70 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
12c80 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12c90 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
12ca0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12cb0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12cc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12cd0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12ce0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12cf0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12d00 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12d10 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12d30 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12d40 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
12d50 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
12d60 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
12d70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
12d80 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
12d90 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
12da0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12db0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12dc0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12dd0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12de0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12df0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12e00 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12e10 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12e20 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12e30 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12e40 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
12e50 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
12e60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e70 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
12e80 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
12e90 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
12ea0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12eb0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12ec0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12ed0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12ee0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12ef0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12f00 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12f10 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12f20 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12f30 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12f40 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
12f50 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
12f60 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
12f70 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
12f80 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
12f90 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
12fa0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12fb0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12fc0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12fd0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12fe0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12ff0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
13000 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
13010 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
13020 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
13030 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
13040 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13050 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
13060 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
13070 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
13080 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
13090 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
130c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
130d0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
130e0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
130f0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
13100 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
13110 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
13120 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
13130 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
13140 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
13150 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
13160 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
13170 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13180 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
13190 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
131a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
131b0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
131c0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
131d0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
131e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
131f0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
13200 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
13210 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
13220 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
13230 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
13240 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
13250 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
13260 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
13270 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
13280 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
13290 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
132a0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
132b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
132c0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
132d0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
132e0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
132f0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
13300 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
13310 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13320 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
13330 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
13340 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
13350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13360 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
13370 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
13380 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
13390 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
133a0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
133b0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
133c0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
133d0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
133e0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
133f0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
13400 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
13410 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
13420 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
13430 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
13440 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
13450 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
13460 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
13470 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
13480 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
13490 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
134a0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
134b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
134c0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
134d0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
134e0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
134f0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
13500 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
13510 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
13520 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
13530 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
13540 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
13550 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13560 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
13570 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
13580 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
13590 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
135a0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
135b0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
135c0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
135d0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
135e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
135f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13600 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
13610 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13620 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
13630 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
13640 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
13650 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
13660 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
13670 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
13680 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
13690 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
136a0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
136b0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
136c0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
136d0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
136e0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
136f0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
13700 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
13710 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
13720 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13730 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
13740 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
13750 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
13760 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
13770 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
13780 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
13790 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
137a0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
137b0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
137c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
137d0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
137e0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
137f0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
13800 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
13810 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
13820 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
13830 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
13840 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
13850 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
13860 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
13870 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
13880 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13890 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
138a0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
138b0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
138c0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
138d0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
138e0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
138f0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
13900 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
13910 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
13920 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
13930 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
13940 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
13950 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13960 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
13970 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
13980 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
13990 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
139a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
139b0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
139c0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
139d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
139e0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
139f0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
13a00 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
13a10 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13a20 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
13a30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
13a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a50 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
13a60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
13a70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13a80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13a90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13aa0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13ab0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
13ac0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
13ad0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13ae0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13af0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13b00 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13b10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13b20 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
13b30 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
13b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13b50 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
13b60 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
13b70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13b80 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13b90 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13ba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13bb0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13bc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13bd0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
13be0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13bf0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
13c00 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
13c10 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
13c20 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
13c30 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
13c40 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
13c50 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
13c60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
13c70 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
13c80 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13c90 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13ca0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13cb0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13cc0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13cd0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13ce0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13cf0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13d00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13d10 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13d20 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13d30 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13d40 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
13d50 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
13d60 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
13d70 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
13d80 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
13d90 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
13da0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13db0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13dc0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13dd0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13de0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13df0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13e00 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13e10 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13e20 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13e30 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13e40 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
13e50 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
13e60 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
13e90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13ea0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13eb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13ec0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13ed0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13ee0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13ef0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f00 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f20 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13f30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13f40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13f50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13f60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13f70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13f80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
13f90 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
13fa0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13fb0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13fc0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13fe0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13ff0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
14000 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
14010 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
14020 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
14030 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
14040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14050 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
14060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
14070 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
14080 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
14090 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
140a0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
140b0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
140c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
140d0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
140e0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
140f0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
14100 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
14110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14120 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
14130 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
14140 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14150 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14160 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14170 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14180 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14190 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
141a0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
141b0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
141c0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
141d0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
141e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
141f0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
14200 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14210 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
14220 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
14230 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
14240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14250 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
14260 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14270 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
14280 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14290 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
142a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
142b0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
142c0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
142d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
142e0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
142f0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
14300 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
14310 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
14320 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
14330 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
14340 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
14350 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
14360 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
14370 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
14380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14390 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
143a0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
143b0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
143c0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
143d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
143e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
143f0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
14400 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
14410 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
14420 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
14430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14440 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
14450 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
14460 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
14470 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
14480 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
14490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
144a0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
144b0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
144c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
144d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
144e0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
144f0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
14500 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14510 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14520 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14540 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14550 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
14560 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
14570 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
14580 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
14590 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
145a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
145b0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
145c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
145d0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
145e0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
145f0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
14600 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14610 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14630 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
14640 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
14650 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14660 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14670 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14680 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14690 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
146a0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
146b0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
146c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
146d0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
146e0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
146f0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
14700 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14710 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
14720 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
14730 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
14740 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
14750 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14760 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
14770 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14780 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
14790 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
147a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
147b0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
147c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
147d0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
147e0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
147f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
14800 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
14810 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14820 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
14830 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14840 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
14850 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14870 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
14880 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14890 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
148a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
148b0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
148c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
148d0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148e0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
148f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14900 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14910 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14920 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14930 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
14940 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
14950 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14960 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14970 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14980 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
14990 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
149a0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
149b0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
149c0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
149d0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
149e0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
149f0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
14a00 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
14a10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14a20 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
14a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14a40 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
14a50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14a60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14a70 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
14a80 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14a90 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
14aa0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
14ab0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14ac0 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
14ad0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
14ae0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
14af0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
14b00 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
14b10 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
14b20 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
14b30 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
14b40 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
14b50 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
14b60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b70 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
14b80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
14b90 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
14ba0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
14bb0 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
14bc0 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
14bd0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
14be0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
14bf0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
14c00 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
14c10 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
14c20 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
14c30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14c40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14c50 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
14c60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14c70 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
14c80 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14c90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14ca0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14cb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14cc0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14cd0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14ce0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14cf0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14d00 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14d10 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14d30 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14d40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14d50 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
14d60 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
14d70 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
14d80 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
14d90 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
14da0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14db0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14dc0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14dd0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14de0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14df0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14e00 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14e10 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14e20 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14e30 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14e40 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
14e50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14e60 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14e70 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
14e80 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
14e90 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14ea0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14eb0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14ec0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14ed0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14ee0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14ef0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14f00 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14f10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14f20 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14f30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f40 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
14f60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14f70 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
14f80 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
14f90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14fb0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14fd0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14fe0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14ff0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
15000 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
15010 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
15020 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15030 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
15040 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
15050 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
15060 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
15080 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
15090 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
150a0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
150b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
150c0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
150d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
150e0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
150f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
15100 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
15110 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15120 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15130 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15140 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
15150 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15160 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
15170 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
15180 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
15190 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
151a0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
151b0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
151c0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
151d0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
151e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
151f0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
15200 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
15210 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
15220 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
15230 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
15240 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
15250 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
15260 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
15270 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
15280 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
15290 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
152a0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
152b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152c0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
152d0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
152e0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
152f0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
15300 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
15310 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
15320 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
15330 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
15340 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15350 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
15360 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
15370 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
15380 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
15390 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
153a0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
153b0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
153c0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
153d0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
153e0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
153f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
15400 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
15410 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
15420 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
15430 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
15440 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
15450 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
15460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15470 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
15480 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
15490 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
154a0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
154b0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
154c0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
154d0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
154e0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
154f0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
15500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15510 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
15520 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
15530 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
15540 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
15550 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15560 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
15570 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
15580 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
15590 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
155a0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
155b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
155c0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
155d0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
155e0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
155f0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
15600 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
15610 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
15620 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
15630 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
15640 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
15650 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
15660 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
15670 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
15680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15690 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
156a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
156b0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
156c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
156d0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
156e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
156f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
15700 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
15710 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
15720 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
15730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15740 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
15750 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
15760 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
15770 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15780 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
15790 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
157a0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
157b0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
157c0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
157d0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
157e0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
157f0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
15800 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
15810 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
15820 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
15830 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
15840 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
15850 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
15860 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15870 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
15880 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
15890 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
158a0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
158b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
158c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
158d0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
158e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
158f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
15900 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15910 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
15920 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15930 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15940 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
15950 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15960 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
15970 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
15980 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
15990 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
159a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
159b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
159c0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
159d0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
159e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
159f0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
15a00 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15a10 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
15a20 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15a30 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15a50 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15a60 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15a70 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
15a80 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
15a90 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
15aa0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15ab0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15ac0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
15ad0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
15ae0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15af0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
15b00 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
15b10 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
15b20 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15b30 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15b40 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
15b50 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
15b60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b70 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15b90 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
15ba0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15bb0 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15bc0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15bd0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15be0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15bf0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15c00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15c10 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15c20 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15c30 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15c40 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
15c50 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
15c60 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15c70 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
15c80 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
15c90 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
15ca0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15cb0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15cc0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15cd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15ce0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15cf0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15d00 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15d10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15d20 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15d30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15d40 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15d50 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15d60 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15d70 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15d80 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15d90 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15da0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15db0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15dc0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15dd0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15de0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15df0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15e00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15e20 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15e30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15e40 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15e60 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
15e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15e80 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15e90 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15ea0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15eb0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15ec0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15ed0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15ee0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15ef0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15f00 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15f10 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15f20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15f30 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15f40 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
15f50 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
15f60 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
15f70 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
15f80 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
15f90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15fa0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15fb0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15fc0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15fd0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15fe0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15ff0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
16000 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
16010 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
16020 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
16030 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
16040 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16050 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16060 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16070 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16090 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
160a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
160b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
160c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
160d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
160e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
160f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16100 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16110 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
16120 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16130 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
16140 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
16150 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16170 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
16180 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16190 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
161a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
161b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
161c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
161d0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
161e0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
161f0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
16200 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16210 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
16220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16240 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
16250 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16260 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16270 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
16280 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
16290 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
162a0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
162b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
162c0 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
162d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
162e0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
162f0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
16300 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
16310 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16320 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
16330 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
16340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
16350 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
16360 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16370 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
16380 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
16390 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
163a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
163c0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
163d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
163e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
163f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16400 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
16410 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16420 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16430 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
16440 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
16450 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16460 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
16470 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
16480 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
16490 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
164a0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
164b0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
164c0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
164d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
164e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
164f0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16510 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
16520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16530 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
16540 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16560 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
16570 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16580 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16590 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
165a0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
165b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
165c0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
165d0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
165e0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
165f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
16600 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
16610 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
16620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16630 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
16640 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
16650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
16660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16670 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16680 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
16690 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
166a0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
166b0 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
166c0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
166d0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
166e0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
166f0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
16700 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
16710 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
16720 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
16730 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
16740 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
16750 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
16760 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
16770 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
16780 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
16790 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
167a0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
167b0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
167c0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
167d0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
167e0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
167f0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
16800 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
16810 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
16820 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
16830 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16840 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
16850 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
16860 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
16870 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16880 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
16890 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
168a0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
168b0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
168c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
168d0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
168e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
168f0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
16900 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
16910 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
16920 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16930 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16940 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16950 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
16960 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
16970 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
16980 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16990 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
169a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
169b0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
169c0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
169d0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
169e0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
169f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16a00 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
16a10 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
16a20 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16a30 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16a40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
16a50 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
16a60 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16a70 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
16a80 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
16a90 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
16aa0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16ab0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16ac0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16ad0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
16ae0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
16af0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16b10 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
16b20 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16b30 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16b40 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
16b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16b60 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16b70 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
16b80 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
16b90 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16ba0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16bb0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16bc0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16bd0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16be0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16bf0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16c00 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16c10 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16c20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16c30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16c40 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16c50 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
16c60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
16c70 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
16c80 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
16c90 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
16ca0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16cb0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16cc0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16cd0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16ce0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16cf0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16d00 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16d10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16d20 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16d30 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16d40 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
16d50 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
16d60 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
16d70 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
16d80 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
16d90 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
16da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16db0 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16dc0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16dd0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16de0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16df0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16e00 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16e10 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16e20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16e30 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16e40 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
16e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16e60 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16e70 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
16e80 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16e90 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
16ea0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16eb0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16ec0 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16ed0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16ee0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16ef0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16f00 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16f10 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16f20 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16f30 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16f40 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16f50 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
16f60 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
16f70 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
16f80 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16f90 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
16fa0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16fb0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16fc0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16fd0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16fe0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16ff0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
17000 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17010 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
17020 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
17030 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
17040 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
17050 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
17060 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
17070 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
17080 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
17090 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
170a0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
170b0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
170c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
170d0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
170e0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
170f0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
17100 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
17110 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
17120 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
17130 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
17140 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
17150 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
17160 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
17170 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17190 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
171a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
171b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
171c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
171d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
171e0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
171f0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
17200 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
17210 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
17220 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
17230 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
17240 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
17250 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17260 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
17270 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
17280 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17290 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
172b0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
172c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
172d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
172e0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
172f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
17300 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
17310 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
17320 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
17330 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
17340 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
17350 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
17360 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
17370 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
17380 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
17390 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
173a0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
173b0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
173c0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
173d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
173e0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
173f0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
17400 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
17410 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
17420 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
17430 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
17440 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
17450 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17460 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
17470 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17480 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
17490 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
174a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
174b0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
174c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
174d0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
174e0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
174f0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
17500 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
17510 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
17520 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17530 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
17540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17550 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
17560 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
17570 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
17580 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
17590 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
175a0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
175b0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
175c0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
175d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
175e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
175f0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
17600 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
17610 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
17620 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
17630 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
17640 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
17650 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17660 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
17670 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
17680 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
17690 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
176a0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
176b0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
176c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
176d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
176e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
176f0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
17700 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
17710 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
17720 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
17730 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
17740 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
17750 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
17760 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
17770 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
17780 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
17790 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
177a0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
177b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
177c0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
177d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
177e0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
177f0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
17800 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
17810 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
17820 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
17830 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
17840 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
17850 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
17860 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
17870 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
17880 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
17890 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
178a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
178b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
178c0 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
178d0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
178e0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
178f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
17900 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
17910 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
17920 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17930 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17940 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
17950 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
17960 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
17970 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
17980 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
17990 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
179a0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
179b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
179c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
179d0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
179e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
179f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17a00 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
17a10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17a20 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17a30 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17a40 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
17a50 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
17a60 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
17a70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
17a80 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
17a90 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
17aa0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17ab0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17ac0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
17ad0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
17ae0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
17af0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
17b00 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
17b10 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
17b20 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17b40 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
17b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17b60 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
17b70 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17b90 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
17ba0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17bb0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17bc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17bd0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17be0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17bf0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17c00 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17c10 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17c20 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17c30 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17c40 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
17c50 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
17c60 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
17c70 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
17c80 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
17c90 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
17ca0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17cb0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17cc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17ce0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17cf0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17d00 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17d20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17d30 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17d40 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
17d50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
17d60 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
17d70 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
17d80 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
17d90 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
17da0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17db0 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17dc0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17dd0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17de0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17df0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17e00 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17e10 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17e20 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17e30 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17e40 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
17e50 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
17e60 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
17e70 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
17e80 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
17e90 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
17ea0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17eb0 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17ec0 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17ed0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17ee0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17ef0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17f00 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17f10 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17f20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17f30 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17f40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17f50 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17f60 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
17f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17f80 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
17f90 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17fa0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17fb0 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17fc0 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17fd0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17fe0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17ff0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
18000 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
18010 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
18020 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
18030 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
18040 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
18050 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
18060 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
18070 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
18080 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
18090 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
180a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
180b0 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
180c0 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
180d0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
180e0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
180f0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
18100 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
18110 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
18120 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
18130 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
18140 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
18150 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
18160 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
18170 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
18180 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
18190 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
181a0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
181b0 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
181c0 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
181d0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
181e0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
181f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
18200 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18210 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18220 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
18230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
18240 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  RREF_SIZE.** <dd
18250 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
18260 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
18270 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73  E option accepts
18280 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
18290 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28  ter.** of type (
182a0 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76  int) - the new v
182b0 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74  alue of the sort
182c0 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a  er-reference siz
182d0 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20  e threshold..** 
182e0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51  Usually, when SQ
182f0 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74  Lite uses an ext
18300 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72  ernal sort to or
18310 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f  der records acco
18320 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f  rding.** to an O
18330 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
18340 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69  all fields requi
18350 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  red by the calle
18360 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e  r are present in
18370 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72   the.** sorted r
18380 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c  ecords. However,
18390 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   if SQLite deter
183a0 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74  mines based on t
183b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
183c0 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63  .** of a table c
183d0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76  olumn that its v
183e0 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  alues are likely
183f0 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67   to be very larg
18400 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68  e - larger.** th
18410 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65  an the configure
18420 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  d sorter-referen
18430 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
18440 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72  d - then a refer
18450 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65  ence.** is store
18460 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64  d in each sorted
18470 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20   record and the 
18480 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20  required column 
18490 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a  values loaded.**
184a0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
184b0 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72  se as records ar
184c0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f  e returned in so
184d0 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20  rted order. The 
184e0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
184f0 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
18500 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65   is to never use
18510 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
18520 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  on. Specifying a
18530 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61   .** negative va
18540 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
18550 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65  ion restores the
18560 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
18570 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  ur..** This opti
18580 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18590 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
185a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
185b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
185c0 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46  NABLE_SORTER_REF
185d0 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65  ERENCES] compile
185e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
185f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
18600 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18610 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18620 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d  E_CONFIG_MEMDB_M
18630 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68  AXSIZE.** <dd>Th
18640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18650 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70  MEMDB_MAXSIZE op
18660 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
18670 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36  ** [sqlite3_int6
18690 34 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  4] parameter whi
186a0 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
186b0 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66  t maximum size f
186c0 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a  or an in-memory.
186d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ** database crea
186e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
186f0 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
18700 5d 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74  ].  This default
18710 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65   maximum.** size
18720 20 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64   can be adjusted
18730 20 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20   up or down for 
18740 69 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62  individual datab
18750 61 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  ases using the.*
18760 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
18770 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c  SIZE_LIMIT] [sql
18780 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
18790 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e  l|file-control].
187a0 20 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e    If this.** con
187b0 66 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69  figuration setti
187c0 6e 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64  ng is never used
187d0 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
187e0 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65  lt maximum is de
187f0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
18800 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42  he [SQLITE_MEMDB
18810 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45  _DEFAULT_MAXSIZE
18820 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18830 70 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a  ption.  If that.
18840 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
18850 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65  option is not se
18860 74 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  t, then the defa
18870 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31  ult maximum is 1
18880 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f  073741824..** </
18890 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
188a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
188b0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
188c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
188d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
188e0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
188f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18900 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18910 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
18920 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
18930 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18940 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
18950 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18960 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18970 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18980 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
18990 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
189a0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
189b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189c0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
189d0 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
189e0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
189f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18a00 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
18a10 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18a20 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a40 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
18a50 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
18a60 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
18a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
18a90 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
18aa0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
18ac0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
18ad0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18ae0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18af0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18b00 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
18b10 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
18b20 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
18b30 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
18b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
18b50 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
18b60 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
18b70 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
18b80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18b90 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18ba0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18bc0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18bd0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18bf0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18c00 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c20 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18c30 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
18c40 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
18c60 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
18c70 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
18c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18c90 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18ca0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18cb0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18cd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18ce0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18cf0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18d00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18d10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18d20 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18d30 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
18d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18d50 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
18d60 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
18d70 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18d90 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18da0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18db0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18dc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18dd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18de0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18df0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e10 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18e20 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18e30 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
18e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18e50 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
18e60 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
18e70 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
18e80 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
18e90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18ea0 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
18eb0 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
18ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ed0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
18ee0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
18ef0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
18f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18f10 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18f20 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20  IZE      28  /* 
18f30 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
18f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f50 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
18f60 20 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71         29  /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a  lite3_int64 */..
18f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18f90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18fa0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18fb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
18fc0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
18fd0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
18fe0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
18ff0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19000 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
19010 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
19020 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
19030 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
19040 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
19050 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
19060 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19070 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
19080 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
19090 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
190a0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
190b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
190c0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
190d0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
190e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
190f0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
19100 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
19110 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
19120 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
19130 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
19140 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
19150 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
19170 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
19180 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
19190 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
191a0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
191b0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
191c0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
191d0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
191e0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
191f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19200 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IDE]].** <dt>SQL
19210 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19220 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
19230 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19240 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
19250 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19260 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
19270 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
19280 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
19290 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
192a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
192b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
192c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
192d0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
192e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
192f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
19300 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
19310 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
19320 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
19330 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
19340 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
19350 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
19360 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
19370 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19380 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
19390 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
193a0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
193b0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
193c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
193d0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
193e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
193f0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
19400 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
19410 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
19420 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
19430 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
19440 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19450 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
19460 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
19470 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
19480 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19490 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
194a0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
194b0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
194c0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
194d0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
194e0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
194f0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
19500 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
19510 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
19520 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
19530 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
19540 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19550 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
19560 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
19570 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
19580 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
19590 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
195a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
195b0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
195c0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
195d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
195e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
195f0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
19600 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
19610 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
19620 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
19630 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
19640 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
19650 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
19660 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
19670 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
19680 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
19690 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
196a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
196b0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
196c0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
196d0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
196e0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
196f0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
19700 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
19710 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
19720 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
19730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
19740 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
19750 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
19760 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
19770 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19780 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19790 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
197a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
197b0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
197c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
197d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
197e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
197f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
19800 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19810 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19820 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19830 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19840 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19860 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19870 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19880 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19890 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
198a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
198b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
198c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
198d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
198e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
198f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19900 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19910 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19920 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19930 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19940 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19950 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19960 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19970 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19980 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19990 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
199a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
199b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
199c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
199d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
199e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
199f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
19a00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19a10 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d  ENABLE_TRIGGER]]
19a20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19a30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19a40 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
19a50 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19a60 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19a70 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
19a80 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19a90 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
19aa0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
19ab0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
19ac0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
19ad0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19ae0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19af0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19b00 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
19b10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19b20 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
19b30 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19b40 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
19b50 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
19b60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19b70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19b80 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19b90 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
19ba0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19bb0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
19bc0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
19bd0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19be0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19bf0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19c00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19c10 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19c20 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19c30 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
19c40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19c50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
19c70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c80 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
19c90 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ER]].** <dt>SQLI
19ca0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19cb0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19cc0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19cd0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19ce0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19cf0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
19d00 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
19d10 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
19d20 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
19d30 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
19d40 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
19d50 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
19d60 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19d70 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19d80 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19d90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19da0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19db0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19dc0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
19dd0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
19de0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
19df0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
19e00 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19e10 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19e20 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
19e30 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19e40 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19e50 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19e60 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
19e70 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19e80 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19e90 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
19ea0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
19eb0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
19ec0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19ed0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19ee0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
19ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19f00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
19f10 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
19f20 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19f30 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
19f50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
19f60 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a  D_EXTENSION]].**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19f90 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
19fa0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19fb0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19fc0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19fd0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
19fe0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19ff0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
1a000 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
1a010 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
1a020 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
1a030 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
1a040 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1a050 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
1a060 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1a070 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
1a080 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
1a090 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a0a0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
1a0b0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
1a0c0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
1a0d0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
1a0e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
1a0f0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
1a100 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1a110 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
1a120 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
1a130 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
1a140 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
1a150 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a160 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
1a170 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
1a180 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
1a190 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a1a0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
1a1b0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
1a1c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1a1d0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
1a1e0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a1f0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
1a200 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
1a210 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
1a220 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
1a230 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
1a240 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
1a250 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a260 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a270 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a280 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a290 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a2a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a2b0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
1a2c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
1a2d0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
1a2e0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1a2f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a300 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a310 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
1a320 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
1a330 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
1a340 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1a350 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a360 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
1a370 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a380 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a390 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  BNAME]] <dt>SQLI
1a3a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a3b0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
1a3c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a3d0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
1a3e0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
1a3f0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
1a400 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
1a410 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
1a420 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1a430 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
1a440 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
1a450 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
1a460 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
1a470 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
1a480 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
1a490 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
1a4a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
1a4b0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
1a4c0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
1a4d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
1a4e0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
1a4f0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
1a500 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
1a510 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
1a520 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
1a530 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
1a540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a550 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
1a560 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1a570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a580 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20  CKPT_ON_CLOSE]] 
1a590 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a5a0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a5b0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
1a5c0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
1a5d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
1a5e0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
1a5f0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
1a600 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
1a610 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
1a620 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
1a630 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
1a640 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
1a650 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
1a660 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
1a670 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
1a680 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
1a690 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
1a6a0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
1a6b0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
1a6c0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
1a6d0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
1a6e0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
1a6f0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
1a700 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a710 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a720 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
1a730 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
1a740 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
1a750 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
1a760 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
1a770 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
1a780 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
1a790 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
1a7a0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1a7b0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
1a7c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1a7d0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1a7e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1a7f0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
1a800 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1a810 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a820 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
1a830 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
1a840 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
1a850 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
1a860 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a870 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
1a880 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1a890 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a8a0 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74  NABLE_QPSG]] <dt
1a8b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a8c0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
1a8d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
1a8e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a8f0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
1a900 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1a910 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1a920 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
1a930 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
1a940 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
1a950 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
1a960 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
1a970 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
1a980 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
1a990 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1a9a0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
1a9b0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
1a9c0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
1a9d0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
1a9e0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
1a9f0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
1aa00 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
1aa10 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
1aa20 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
1aa30 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
1aa40 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
1aa50 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
1aa60 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
1aa70 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
1aa80 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
1aa90 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
1aaa0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
1aab0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
1aac0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1aad0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
1aae0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
1aaf0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
1ab00 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
1ab10 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
1ab20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1ab30 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
1ab40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
1ab50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
1ab60 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
1ab70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1ab80 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
1ab90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1aba0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1abb0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
1abc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1abd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1abe0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1abf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
1ac00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1ac10 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
1ac20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
1ac30 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1ac40 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1ac50 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
1ac60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1ac70 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1ac80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1ac90 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1aca0 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1acb0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1acc0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1acd0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1ace0 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1acf0 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1ad00 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1ad10 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1ad20 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1ad30 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1ad40 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1ad50 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1ad60 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1ad70 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1ad80 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1ad90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ada0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1adb0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1adc0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1add0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1ade0 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1adf0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1ae00 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1ae10 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1ae20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1ae30 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1ae40 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1ae50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1ae60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1ae70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1ae80 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1ae90 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1aea0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1aeb0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1aec0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1aed0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1aee0 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1aef0 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1af00 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1af10 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1af20 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d  _RESET_DATABASE]
1af30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1af40 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1af50 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  BASE</dt>.** <dd
1af60 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45  > Set the SQLITE
1af70 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1af80 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e  DATABASE flag an
1af90 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56  d then run.** [V
1afa0 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20  ACUUM] in order 
1afb0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62  to reset a datab
1afc0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65  ase back to an e
1afd0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mpty database.**
1afe0 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20   with no schema 
1aff0 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20  and no content. 
1b000 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  The following pr
1b010 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e  ocess works even
1b020 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20   for.** a badly 
1b030 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61  corrupted databa
1b040 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e  se file:.** <ol>
1b050 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20  .** <li> If the 
1b060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b070 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65  ion is newly ope
1b080 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69  ned, make sure i
1b090 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a  t has read the.*
1b0a0 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20  *      database 
1b0b0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72  schema by prepar
1b0c0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64  ing then discard
1b0d0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61  ing some query a
1b0e0 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20  gainst the.**   
1b0f0 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20     database, or 
1b100 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
1b110 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1b120 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e  adata(), ignorin
1b130 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72  g any.**      er
1b140 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70  rors.  This step
1b150 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61   is only necessa
1b160 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ry if the applic
1b170 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f  ation desires to
1b180 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68   keep.**      th
1b190 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41  e database in WA
1b1a0 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65  L mode after the
1b1b0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73   reset if it was
1b1c0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66   in WAL mode bef
1b1d0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  ore.**      the 
1b1e0 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e  reset.  .** <li>
1b1f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1b200 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1b210 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b220 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a  ABASE, 1, 0);.**
1b230 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65   <li> [sqlite3_e
1b240 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55  xec](db, "[VACUU
1b250 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  M]", 0, 0, 0);.*
1b260 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1b270 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1b280 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1b290 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20  ET_DATABASE, 0, 
1b2a0 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20  0);.** </ol>.** 
1b2b0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e  Because resettin
1b2c0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  g a database is 
1b2d0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20  destructive and 
1b2e0 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68  irreversible, th
1b2f0 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71  e.** process req
1b300 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66  uires the use of
1b310 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50   this obscure AP
1b320 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73  I and multiple s
1b330 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20  teps to help.** 
1b340 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64  ensure that it d
1b350 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62  oes not happen b
1b360 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a  y accident..**.*
1b370 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b380 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20  FIG_DEFENSIVE]] 
1b390 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1b3a0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64  FIG_DEFENSIVE</d
1b3b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
1b3c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45  LITE_DBCONFIG_DE
1b3d0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61  FENSIVE option a
1b3e0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1b3f0 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22  tivates the.** "
1b400 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20  defensive" flag 
1b410 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
1b420 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e  onnection.  When
1b430 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a   the defensive.*
1b440 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65  * flag is enable
1b450 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74  d, language feat
1b460 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20  ures that allow 
1b470 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20  ordinary SQL to 
1b480 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79  .** deliberately
1b490 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74   corrupt the dat
1b4a0 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64  abase file are d
1b4b0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69  isabled.  The di
1b4c0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72  sabled.** featur
1b4d0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61  es include but a
1b4e0 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74  re not limited t
1b4f0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  o the following:
1b500 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1b510 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69   The [PRAGMA wri
1b520 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d  table_schema=ON]
1b530 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c   statement..** <
1b540 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68  li> Writes to th
1b550 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65  e [sqlite_dbpage
1b560 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  ] virtual table.
1b570 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20  .** <li> Direct 
1b580 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f  writes to [shado
1b590 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f  w tables]..** </
1b5a0 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ul>.** </dd>.**.
1b5b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1b5c0 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43  NFIG_WRITABLE_SC
1b5d0 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEMA]] <dt>SQLIT
1b5e0 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41  E_DBCONFIG_WRITA
1b5f0 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e 0a  BLE_SCHEMA</dt>.
1b600 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
1b610 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41  E_DBCONFIG_WRITA
1b620 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69 6f  BLE_SCHEMA optio
1b630 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1b640 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a  eactivates the.*
1b650 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68 65  * "writable_sche
1b660 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20 68  ma" flag. This h
1b670 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  as the same effe
1b680 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63 61  ct and is logica
1b690 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a 2a  lly equivalent.*
1b6a0 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50 52  * to setting [PR
1b6b0 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63  AGMA writable_sc
1b6c0 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41  hema=ON] or [PRA
1b6d0 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
1b6e0 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65  ema=OFF]..** The
1b6f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b700 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20  to this setting 
1b710 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
1b720 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
1b730 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69 74  ble .** the writ
1b740 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f 73  able_schema, pos
1b750 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1b760 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c  writable_schema,
1b770 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 0a   or negative to.
1b780 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  ** leave the set
1b790 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 20  ting unchanged. 
1b7a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1b7b0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1b7c0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  r to an.** integ
1b7d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  er into which is
1b7e0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
1b7f0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
1b800 68 65 72 20 74 68 65 20 77 72 69 74 61 62 6c 65  her the writable
1b810 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65 6e  _schema.** is en
1b820 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
1b830 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  d following this
1b840 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   call..** </dd>.
1b850 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1b860 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b870 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
1b880 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
1b890 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
1b8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b8b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
1b8c0 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
1b8d0 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
1b8e0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
1b8f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b900 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
1b910 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
1b920 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b930 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b940 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
1b950 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
1b960 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b970 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b980 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
1b990 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
1b9a0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b9c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
1b9d0 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
1b9e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b9f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ba00 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1ba10 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30  ON_CLOSE      10
1ba20 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  06 /* int int* *
1ba30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ba40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1ba50 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20  _QPSG           
1ba60 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1007 /* int int*
1ba70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ba80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47  TE_DBCONFIG_TRIG
1ba90 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20  GER_EQP         
1baa0 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e    1008 /* int in
1bab0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1bac0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45  LITE_DBCONFIG_RE
1bad0 53 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20  SET_DATABASE    
1bae0 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20      1009 /* int 
1baf0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1bb00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1bb10 44 45 46 45 4e 53 49 56 45 20 20 20 20 20 20 20  DEFENSIVE       
1bb20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69 6e        1010 /* in
1bb30 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1bb40 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1bb50 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d  G_WRITABLE_SCHEM
1bb60 41 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a 20  A       1011 /* 
1bb70 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1bb80 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1bb90 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20  FIG_MAX         
1bba0 20 20 20 20 20 20 20 20 20 20 31 30 31 31 20 2f            1011 /
1bbb0 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46  * Largest DBCONF
1bbc0 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  IG */../*.** CAP
1bbd0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
1bbe0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
1bbf0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
1bc00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1bc10 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1bc20 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1bc30 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
1bc40 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
1bc50 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
1bc60 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1bc70 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
1bc80 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
1bc90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
1bca0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
1bcb0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1bcc0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
1bcd0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1bce0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
1bcf0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
1bd00 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
1bd10 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
1bd20 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
1bd30 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
1bd40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1bd50 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
1bd60 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
1bd70 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
1bd80 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
1bd90 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
1bda0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
1bdb0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
1bdc0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
1bdd0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
1bde0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
1bdf0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
1be00 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
1be10 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
1be20 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1be30 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1be40 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1be50 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1be60 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1be70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1be80 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1be90 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1bea0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1beb0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1bec0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1bed0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1bee0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1bef0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1bf00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
1bf10 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1bf20 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61  ) interface usua
1bf30 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1bf40 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68  [rowid] of.** th
1bf50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
1bf60 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1bf70 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
1bf80 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
1bf90 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
1bfa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bfb0 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e  n D. ^Inserts in
1bfc0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
1bfd0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
1bfe0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e  t.** recorded. ^
1bff0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
1c000 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
1c010 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76  rowid tables hav
1c020 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
1c030 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62  .** on the datab
1c040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1c050 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  , then sqlite3_l
1c060 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c070 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  (D) returns .** 
1c080 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  zero..**.** As w
1c090 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74  ell as being set
1c0a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
1c0b0 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72  s rows are inser
1c0c0 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73  ted into databas
1c0d0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65  e.** tables, the
1c0e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c0f0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1c100 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c   may be set expl
1c110 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71  icitly by.** [sq
1c120 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1c130 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1c140 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61  *.** Some virtua
1c150 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1c160 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45  tations may INSE
1c170 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77  RT rows into row
1c180 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20  id tables as.** 
1c190 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69  part of committi
1c1a0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
1c1b0 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20   (e.g. to flush 
1c1c0 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64  data accumulated
1c1d0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f   in memory.** to
1c1e0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20   disk). In this 
1c1f0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  case subsequent 
1c200 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75  calls to this fu
1c210 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68  nction return th
1c220 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63  e rowid.** assoc
1c230 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65  iated with these
1c240 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54   internal INSERT
1c250 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69   operations, whi
1c260 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20  ch leads to .** 
1c270 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75  unintuitive resu
1c280 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62  lts. Virtual tab
1c290 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1c2a0 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65  ns that do write
1c2b0 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62   to rowid.** tab
1c2c0 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20  les in this way 
1c2d0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70  can avoid this p
1c2e0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72  roblem by restor
1c2f0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1c300 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65   .** rowid value
1c310 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1c320 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1c330 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20  rowid()] before 
1c340 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f  returning .** co
1c350 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65  ntrol to the use
1c360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  r..**.** ^(If an
1c370 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
1c380 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1c390 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  r then this rout
1c3a0 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74  ine will .** ret
1c3b0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
1c3c0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20  of the inserted 
1c3d0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
1c3e0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a  he trigger is .*
1c3f0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20  * running. Once 
1c400 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1c410 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61  ram ends, the va
1c420 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
1c430 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
1c440 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
1c450 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
1c460 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66  he trigger was f
1c470 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  ired.)^.**.** ^A
1c480 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
1c490 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
1c4a0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1c4b0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
1c4c0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1c4d0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
1c4e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1c4f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1c500 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
1c510 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
1c520 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
1c530 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
1c540 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
1c550 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
1c560 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
1c570 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
1c580 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
1c590 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
1c5a0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
1c5b0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
1c5c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
1c5d0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
1c5e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1c5f0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
1c600 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
1c610 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
1c620 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
1c630 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
1c640 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
1c650 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
1c660 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
1c670 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
1c680 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
1c690 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
1c6a0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
1c6b0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
1c6c0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
1c6d0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
1c6e0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
1c6f0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
1c700 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
1c710 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
1c720 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
1c730 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
1c740 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1c750 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
1c760 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
1c770 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
1c780 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
1c790 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1c7a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1c7b0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
1c7c0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
1c7d0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
1c7e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c7f0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
1c800 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1c810 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
1c820 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1c830 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
1c840 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
1c850 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
1c860 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1c870 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1c880 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c890 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
1c8a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
1c8b0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
1c8c0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
1c8d0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
1c8e0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
1c8f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1c900 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
1c910 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1c920 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c930 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20  PI3REF: Set the 
1c940 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1c950 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48  d value..** METH
1c960 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c970 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65  * The sqlite3_se
1c980 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1c990 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64  wid(D, R) method
1c9a0 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c   allows the appl
1c9b0 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65  ication to.** se
1c9c0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1c9d0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  rned by calling 
1c9e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1c9f0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20  ert_rowid(D) to 
1ca00 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e  R .** without in
1ca10 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e  serting a row in
1ca20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
1ca30 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ca40 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1ca50 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c  _rowid(sqlite3*,
1ca60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
1ca70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ca80 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
1ca90 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1caa0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1cab0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1cac0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1cad0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1cae0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
1caf0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
1cb00 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
1cb10 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
1cb20 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
1cb30 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
1cb40 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
1cb50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1cb60 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
1cb70 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
1cb80 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
1cb90 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1cba0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1cbb0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
1cbc0 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
1cbd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
1cbe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
1cbf0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
1cc00 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
1cc10 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
1cc20 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1cc30 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
1cc40 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
1cc50 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
1cc60 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
1cc70 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1cc80 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
1cc90 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1cca0 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
1ccb0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1ccc0 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
1ccd0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
1cce0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1ccf0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1cd00 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
1cd10 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
1cd20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1cd30 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
1cd40 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
1cd50 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
1cd60 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1cd70 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
1cd80 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
1cd90 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
1cda0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
1cdb0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
1cdc0 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
1cdd0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
1cde0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
1cdf0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
1ce00 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
1ce10 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
1ce20 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
1ce30 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1ce40 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
1ce50 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
1ce60 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
1ce70 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
1ce80 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
1ce90 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
1cea0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1ceb0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
1cec0 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
1ced0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1cee0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
1cef0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
1cf00 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
1cf10 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
1cf20 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
1cf30 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
1cf40 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
1cf50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1cf60 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
1cf70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1cf80 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
1cf90 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
1cfa0 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
1cfb0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
1cfc0 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
1cfd0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
1cfe0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
1cff0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
1d000 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1d010 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
1d020 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
1d030 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
1d040 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
1d050 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1d060 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1d070 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
1d080 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
1d090 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
1d0a0 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
1d0b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
1d0c0 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
1d0d0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
1d0e0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
1d0f0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
1d100 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1d110 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
1d120 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
1d130 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
1d140 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
1d150 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
1d160 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
1d170 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
1d180 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1d190 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
1d1a0 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
1d1b0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
1d1c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1d1d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1d1e0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
1d1f0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
1d200 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
1d210 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
1d220 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
1d230 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
1d240 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
1d250 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
1d260 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
1d270 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1d280 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
1d290 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
1d2a0 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
1d2b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1d2c0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
1d2d0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
1d2e0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
1d2f0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1d300 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
1d310 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
1d320 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1d330 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1d340 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1d350 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1d360 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1d370 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1d380 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1d390 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1d3a0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1d3b0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1d3c0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1d3d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a  *.** See also:.*
1d3e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74  * <ul>.** <li> t
1d3f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1d400 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1d410 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74  erface.** <li> t
1d420 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  he [count_change
1d430 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  s pragma].** <li
1d440 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  > the [changes()
1d450 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a   SQL function].*
1d460 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61  * <li> the [data
1d470 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d  _version pragma]
1d480 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
1d490 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1d4a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1d4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1d4c0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1d4d0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1d4e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d4f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1d500 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1d510 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1d520 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1d530 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1d540 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1d550 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1d560 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1d570 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1d580 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1d590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5a0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1d5b0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1d5c0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1d5d0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1d5e0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1d5f0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1d600 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1d610 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1d620 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1d630 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d640 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1d650 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1d660 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1d670 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1d680 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1d690 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1d6a0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1d6b0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1d6c0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1d6d0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1d6e0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1d6f0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1d700 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1d710 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1d720 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1d730 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1d740 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1d750 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1d760 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  D)] interface on
1d770 6c 79 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e  ly reports the n
1d780 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73  umber.** of rows
1d790 20 74 68 61 74 20 63 68 61 6e 67 65 64 20 64 75   that changed du
1d7a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1d7b0 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20 64  nt run against d
1d7c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
1d7d0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68  ction D.  Any ch
1d7e0 61 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20 64  anges by other d
1d7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d800 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  ons are ignored.
1d810 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63 68  .** To detect ch
1d820 61 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61 20  anges against a 
1d830 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 72  database file fr
1d840 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  om other databas
1d850 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  e.** connections
1d860 20 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d 41   use the [PRAGMA
1d870 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63   data_version] c
1d880 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a  ommand or the.**
1d890 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44   [SQLITE_FCNTL_D
1d8a0 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69  ATA_VERSION] [fi
1d8b0 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20  le control]..** 
1d8c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1d8d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1d8e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1d8f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1d900 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1d910 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1d920 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1d930 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1d940 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1d950 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1d960 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1d970 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ful..**.** See a
1d980 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  lso:.** <ul>.** 
1d990 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65  <li> the [sqlite
1d9a0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1d9b0 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74  erface.** <li> t
1d9c0 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  he [count_change
1d9d0 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  s pragma].** <li
1d9e0 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  > the [changes()
1d9f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a   SQL function].*
1da00 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61  * <li> the [data
1da10 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d  _version pragma]
1da20 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51  .** <li> the [SQ
1da30 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
1da40 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63  VERSION] [file c
1da50 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ontrol].** </ul>
1da60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1da70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1da80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1da90 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1daa0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1dab0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1dac0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1dad0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1dae0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1daf0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1db00 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1db10 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1db20 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1db30 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1db40 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1db50 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1db60 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1db70 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1db80 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1db90 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1dba0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1dbb0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1dbc0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1dbd0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1dbe0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1dbf0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1dc00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1dc10 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1dc20 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1dc30 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1dc40 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1dc50 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1dc60 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1dc70 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1dc80 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1dc90 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1dca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dcb0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1dcc0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1dcd0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1dce0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1dcf0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1dd00 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1dd10 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1dd20 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1dd30 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1dd40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1dd50 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1dd60 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1dd70 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1dd80 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1dd90 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1dda0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1ddb0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1ddc0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1ddd0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1dde0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1ddf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1de00 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1de10 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1de20 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1de30 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1de40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1de50 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1de60 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1de70 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1de80 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1de90 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1dea0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1deb0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1dec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1ded0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1dee0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1def0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1df00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1df10 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1df20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1df30 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1df40 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1df50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1df60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1df70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1df80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1df90 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1dfa0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1dfb0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1dfc0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1dfd0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1dfe0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1dff0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1e000 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e010 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1e020 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1e030 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1e040 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1e050 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1e060 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1e070 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1e080 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1e090 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1e0a0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1e0b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e0c0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1e0d0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1e0e0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1e0f0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1e100 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1e110 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1e120 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1e130 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1e140 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1e150 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1e160 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1e170 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1e180 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1e190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e1a0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1e1b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1e1c0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1e1d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1e1e0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1e1f0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1e200 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1e210 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1e220 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1e230 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1e240 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1e250 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1e260 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1e270 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1e280 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1e290 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1e2a0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1e2b0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1e2c0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1e2d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1e2e0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1e2f0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1e300 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1e310 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1e320 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1e330 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1e340 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1e350 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1e360 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1e370 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1e380 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1e390 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1e3a0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1e3b0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1e3c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1e3d0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1e3e0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1e3f0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1e400 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1e410 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1e420 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1e430 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1e440 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1e450 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1e460 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1e470 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1e480 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1e490 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1e4a0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1e4b0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1e4c0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1e4d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1e4e0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1e4f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1e500 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1e510 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1e520 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1e530 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1e540 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1e550 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1e560 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1e570 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e580 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1e590 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1e5a0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1e5b0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1e5c0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1e5d0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1e5e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1e5f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1e600 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1e610 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1e620 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1e630 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1e640 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1e650 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1e660 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1e670 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1e680 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1e690 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1e6a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1e6b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1e6c0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1e6d0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1e6e0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1e6f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1e700 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1e710 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1e720 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1e730 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1e740 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1e750 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1e760 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1e770 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1e790 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1e7a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e7b0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1e7c0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1e7d0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1e7e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1e7f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1e800 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1e810 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1e820 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1e830 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1e840 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1e850 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1e860 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1e870 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1e880 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1e890 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1e8a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1e8b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1e8c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1e8d0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1e8e0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1e8f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1e900 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1e910 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1e920 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1e930 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1e940 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1e950 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1e960 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1e970 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e980 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1e990 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1e9a0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1e9b0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1e9c0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1e9d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1e9e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1e9f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1ea00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1ea10 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1ea20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1ea30 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1ea40 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1ea50 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1ea60 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1ea70 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1ea80 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1ea90 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1eaa0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1eab0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1eac0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1ead0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1eae0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1eaf0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1eb00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1eb10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1eb20 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1eb30 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1eb40 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1eb50 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1eb60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1eb70 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1eb80 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1eb90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1eba0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1ebb0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1ebc0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1ebd0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1ebe0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1ebf0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1ec00 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1ec10 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1ec20 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1ec30 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1ec40 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1ec50 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1ec60 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1ec70 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1ec80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1ec90 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1eca0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1ecb0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1ecc0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1ecd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1ece0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1ecf0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1ed00 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1ed10 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1ed20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1ed30 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1ed40 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1ed50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1ed60 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1ed70 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1ed80 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1ed90 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1eda0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1edb0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1edc0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1edd0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1ede0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1edf0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1ee00 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1ee10 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1ee20 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1ee30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1ee40 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1ee50 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1ee60 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1ee70 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1ee80 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1ee90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1eea0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1eeb0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1eec0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1eed0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1eee0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1eef0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1ef00 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1ef10 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1ef20 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1ef30 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1ef40 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1ef50 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1ef60 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1ef70 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1ef80 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1ef90 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1efa0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1efb0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1efc0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1efd0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1efe0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1eff0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1f000 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1f010 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1f020 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1f030 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1f040 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1f050 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1f060 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1f070 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1f080 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1f090 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1f0a0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1f0b0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1f0c0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1f0d0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1f0e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1f0f0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1f100 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1f110 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1f120 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1f130 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1f140 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1f150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f160 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1f170 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1f180 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1f190 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1f1a0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1f1b0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1f1c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1f1d0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1f1e0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1f1f0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1f200 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1f210 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1f220 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1f230 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1f240 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1f250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1f260 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1f270 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1f280 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1f290 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1f2a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1f2b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1f2c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1f2d0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1f2e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1f2f0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1f300 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1f310 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1f320 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1f330 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1f340 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1f350 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1f360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f370 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1f380 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1f390 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1f3a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1f3b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1f3c0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1f3d0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1f3e0 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1f3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1f400 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1f410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1f420 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1f430 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1f440 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1f450 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1f460 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1f470 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1f480 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1f490 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1f4a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1f4b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1f4c0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1f4d0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1f4e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1f4f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1f500 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1f510 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1f520 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1f530 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1f540 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1f550 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1f560 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1f570 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1f580 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1f590 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1f5a0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1f5b0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1f5c0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1f5d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1f5e0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1f5f0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1f600 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1f610 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1f620 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1f630 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1f640 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1f650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1f660 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1f670 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1f680 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1f690 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1f6a0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1f6b0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1f6c0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1f6d0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1f6e0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1f6f0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1f700 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1f710 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1f720 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1f730 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1f740 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1f750 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1f760 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1f770 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1f780 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1f790 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1f7a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1f7b0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1f7c0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1f7d0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1f7e0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1f7f0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1f800 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1f810 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1f820 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1f830 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1f840 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1f850 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1f860 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1f870 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f880 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1f890 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1f8a0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1f8b0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1f8c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1f8d0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1f8e0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1f8f0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1f900 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1f910 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1f920 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1f930 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1f940 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1f950 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1f960 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1f970 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1f980 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1f990 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1f9a0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1f9b0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1f9c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1f9d0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1f9e0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1f9f0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1fa00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1fa10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1fa20 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1fa30 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1fa40 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1fa50 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1fa60 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1fa70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1fa80 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1fa90 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1faa0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1fab0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1fac0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1fad0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1fae0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1faf0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1fb00 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1fb10 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1fb20 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1fb30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1fb40 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1fb50 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1fb60 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1fb70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1fb80 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1fb90 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1fba0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1fbb0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1fbc0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1fbd0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1fbe0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1fbf0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1fc00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1fc10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1fc20 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1fc30 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1fc40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1fc50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1fc60 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1fc70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1fc80 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1fc90 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1fca0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1fcb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1fcc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1fcd0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1fce0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1fcf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1fd00 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1fd10 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1fd20 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1fd30 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1fd40 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1fd50 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1fd60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1fd70 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1fd80 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1fd90 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1fda0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1fdb0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1fdc0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1fdd0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1fde0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1fdf0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1fe00 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1fe10 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1fe20 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1fe30 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1fe40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1fe50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1fe60 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1fe70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1fe80 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1fe90 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1fea0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1feb0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1fec0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1fed0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1fee0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1fef0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1ff00 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ff10 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1ff20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ff30 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1ff40 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1ff50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1ff60 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1ff70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1ff80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ff90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1ffa0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1ffb0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1ffc0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1ffd0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1ffe0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1fff0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
20000 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
20010 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
20020 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
20030 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
20040 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
20050 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
20060 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
20070 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
20080 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
20090 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
200a0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
200b0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
200c0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
200d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
200e0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
200f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
20100 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
20110 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
20120 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
20130 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
20140 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
20150 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20160 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
20170 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20180 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
20190 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
201a0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
201b0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
201c0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
201d0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
201e0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
201f0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
20200 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
20210 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
20220 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20230 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
20240 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
20250 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
20260 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
20270 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
20280 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
20290 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
202a0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
202b0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
202c0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
202d0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
202e0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
202f0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
20300 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
20310 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
20320 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
20330 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
20340 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
20350 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
20360 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
20370 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
20380 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
20390 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
203a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
203b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
203c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
203d0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
203e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
203f0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
20400 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
20410 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
20420 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
20430 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
20440 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
20450 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
20460 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
20470 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
20480 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
20490 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
204a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
204b0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
204c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
204d0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
204e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
204f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
20500 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
20510 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
20520 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
20530 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
20540 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
20550 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
20560 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
20570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20580 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
20590 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
205a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
205b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
205c0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
205d0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
205e0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
205f0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
20600 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
20610 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20620 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
20630 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
20640 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
20650 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  ns from.** the s
20660 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
20670 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75  printf() .** plu
20680 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
20690 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
206a0 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25  ormats ([%q], [%
206b0 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25  Q], [%w], and [%
206c0 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20  z])..** See the 
206d0 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66  [built-in printf
206e0 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
206f0 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a  n for details..*
20700 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20710 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
20720 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
20730 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
20740 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
20750 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
20760 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
20770 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
20780 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
20790 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
207a0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
207b0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
207c0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
207d0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
207e0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
207f0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
20800 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
20810 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20  _malloc64()] is 
20820 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
20830 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
20840 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
20850 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
20860 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
20870 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20880 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
20890 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
208a0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
208b0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
208c0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
208d0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
208e0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
208f0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
20900 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
20910 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
20920 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
20930 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
20940 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
20950 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
20960 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
20970 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
20980 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
20990 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
209a0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
209b0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
209c0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
209d0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
209e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
209f0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
20a00 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
20a10 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
20a20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
20a30 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
20a40 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
20a50 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
20a60 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
20a70 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
20a80 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
20a90 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
20aa0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
20ab0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
20ac0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
20ad0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
20ae0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
20af0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
20b00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
20b10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
20b20 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
20b30 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
20b40 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
20b50 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
20b60 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
20b70 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
20b80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20b90 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
20ba0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
20bb0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
20bc0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
20bd0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
20be0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
20bf0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
20c00 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
20c10 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
20c20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
20c30 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
20c40 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
20c50 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
20c60 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
20c70 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
20c80 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
20c90 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
20ca0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
20cb0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
20cc0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
20cd0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53  rintf()..**.** S
20ce0 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74  ee also:  [built
20cf0 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b  -in printf()], [
20d00 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e  printf() SQL fun
20d10 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a  ction].*/.char *
20d20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
20d30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
20d40 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
20d50 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
20d60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
20d70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
20d80 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
20d90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
20da0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
20db0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
20dc0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20dd0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
20de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
20df0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
20e00 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
20e10 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
20e20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
20e30 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
20e40 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
20e50 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
20e60 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
20e70 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
20e80 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
20e90 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
20ea0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
20eb0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
20ec0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20ed0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
20ee0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
20ef0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
20f00 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
20f10 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
20f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20f30 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
20f40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20f50 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
20f60 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
20f70 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
20f80 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
20f90 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
20fa0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
20fb0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
20fc0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
20fd0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
20fe0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
20ff0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
21000 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
21010 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
21020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
21030 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
21040 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
21050 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
21060 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
21070 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
21080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
21090 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
210a0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
210b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
210c0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
210d0 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
210e0 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
210f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
21100 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
21110 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
21120 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
21130 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
21140 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
21150 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
21160 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
21170 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
21180 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
21190 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
211a0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
211b0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
211c0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
211d0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
211e0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
211f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
21200 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
21210 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
21220 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
21230 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
21240 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
21250 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
21260 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
21270 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
21280 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
21290 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
212a0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
212b0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
212c0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
212d0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
212e0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
212f0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
21300 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
21310 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
21320 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
21330 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
21340 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
21350 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
21360 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
21370 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
21380 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
21390 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
213a0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
213b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
213c0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
213d0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
213e0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
213f0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
21400 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
21410 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
21420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
21430 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21440 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
21450 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
21460 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
21470 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
21480 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
21490 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
214a0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
214b0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
214c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
214d0 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
214e0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
214f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21500 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
21510 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
21520 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
21530 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
21540 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
21550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21560 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21570 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
21580 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
21590 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
215a0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
215b0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
215c0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
215d0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
215e0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
215f0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
21600 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
21610 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
21620 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
21630 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
21640 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
21650 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
21660 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
21670 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
21680 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
21690 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
216a0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
216b0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
216c0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
216d0 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
216e0 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
216f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21700 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
21710 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
21720 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
21730 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
21740 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
21750 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
21760 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
21770 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
21780 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
21790 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
217a0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
217b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
217c0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
217d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
217e0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
217f0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
21800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
21810 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
21820 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
21830 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
21840 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
21850 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
21860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
21870 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
21880 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
21890 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
218a0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
218b0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
218c0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
218d0 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
218e0 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
218f0 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
21900 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
21910 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
21920 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
21930 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
21940 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
21950 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
21960 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
21970 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
21980 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
21990 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
219a0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
219b0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
219c0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
219d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
219e0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
219f0 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
21a00 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
21a10 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
21a20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
21a30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
21a40 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
21a50 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
21a60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
21a70 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
21a80 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
21a90 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
21aa0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
21ab0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
21ac0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
21ad0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
21ae0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
21af0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
21b00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
21b10 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
21b20 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
21b30 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
21b40 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
21b50 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
21b60 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
21b70 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
21b80 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
21b90 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
21ba0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
21bb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
21bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
21bd0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
21be0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
21bf0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
21c00 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
21c10 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
21c20 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
21c30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
21c40 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
21c50 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
21c60 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
21c70 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
21c80 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
21c90 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
21ca0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
21cb0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
21cc0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
21cd0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
21ce0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
21cf0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
21d00 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
21d10 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
21d20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
21d30 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
21d40 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
21d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
21d60 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
21d70 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
21d80 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
21d90 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
21da0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
21db0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
21dc0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
21dd0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
21de0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
21df0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
21e00 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
21e10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
21e20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
21e30 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
21e40 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
21e50 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
21e60 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
21e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
21e80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
21e90 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
21ea0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
21eb0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
21ec0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
21ed0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
21ee0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
21ef0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
21f00 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
21f10 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
21f20 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
21f30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
21f40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
21f50 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
21f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
21f70 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
21f80 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
21f90 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
21fa0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
21fb0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
21fc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
21fd0 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
21fe0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
21ff0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
22000 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
22010 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
22020 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
22030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
22040 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
22050 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
22060 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
22070 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
22080 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
22090 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
220a0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
220b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
220c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
220d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
220e0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
220f0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
22100 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
22110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
22120 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
22130 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
22140 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
22150 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
22160 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
22170 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
22180 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
22190 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
221a0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
221b0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
221c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
221d0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
221e0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
221f0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
22200 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
22210 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
22220 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
22230 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
22240 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
22250 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
22260 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
22270 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
22280 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22290 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
222a0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
222b0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
222c0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
222d0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
222e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
222f0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
22300 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
22310 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
22320 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
22330 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
22340 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
22350 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
22360 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
22370 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
22380 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
22390 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
223a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
223b0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
223c0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
223d0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
223e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
223f0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
22400 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
22410 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
22420 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
22430 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
22440 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
22450 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
22460 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
22470 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
22480 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
22490 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
224a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
224b0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
224c0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
224d0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
224e0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
224f0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
22500 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
22510 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
22520 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
22530 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
22540 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
22550 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
22560 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
22570 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
22580 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
22590 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
225a0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
225b0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
225c0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
225d0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
225e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
225f0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
22600 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
22610 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
22620 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
22630 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
22640 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
22650 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
22660 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
22670 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
22680 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
22690 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
226a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
226b0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
226c0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
226d0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
226e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
226f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
22700 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
22710 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
22720 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
22730 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
22740 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
22750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
22760 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
22770 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
22780 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
22790 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
227a0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
227b0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
227c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
227d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
227e0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
227f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
22800 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
22810 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
22820 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
22830 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
22840 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
22850 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
22860 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
22870 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
22880 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
22890 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
228a0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
228b0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
228c0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
228d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
228e0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
228f0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
22900 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
22910 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b  OD: sqlite3.** K
22920 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72  EYWORDS: {author
22930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a  izer callback}.*
22940 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
22950 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
22960 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22970 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
22980 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
22990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
229a0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
229b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
229c0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
229d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
229e0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
229f0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
22a00 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
22a10 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
22a20 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
22a30 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
22a40 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
22a50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22a60 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
22a70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
22a80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22a90 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64  16_v2()],.** and
22aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22ab0 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20  e16_v3()].  ^At 
22ac0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
22ad0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
22ae0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
22af0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
22b00 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
22b10 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
22b20 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
22b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22b40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
22b50 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
22b60 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
22b70 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
22b80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22b90 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
22ba0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
22bb0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
22bc0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
22bd0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
22be0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
22bf0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
22c00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
22c10 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
22c20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
22c30 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
22c40 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
22c50 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
22c60 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
22c70 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
22c80 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
22c90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22ca0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
22cb0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
22cc0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
22cd0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
22ce0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
22cf0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
22d00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22d10 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
22d20 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
22d30 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
22d40 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
22d50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
22d60 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
22d70 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
22d80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
22d90 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
22da0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
22db0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
22dc0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
22dd0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
22de0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
22df0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22e00 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
22e10 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
22e20 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
22e30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
22e40 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
22e50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
22e60 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
22e70 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
22e80 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
22e90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
22ea0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
22eb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
22ec0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
22ed0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
22ee0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
22ef0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
22f00 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
22f10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
22f20 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
22f30 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
22f40 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
22f50 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
22f60 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
22f70 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
22f80 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
22f90 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
22fa0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
22fb0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
22fc0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
22fd0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f  e either NULL po
22fe0 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74  inters or zero-t
22ff0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
23000 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69  s.** that contai
23010 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  n additional det
23020 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
23030 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
23040 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69  orized..** Appli
23050 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77  cations must alw
23060 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20  ays be prepared 
23070 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e  to encounter a N
23080 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61  ULL pointer in a
23090 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69  ny.** of the thi
230a0 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  rd through the s
230b0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
230c0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  of the authoriza
230d0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
230e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
230f0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
23100 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
23110 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
23120 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
23130 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
23140 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
23150 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
23160 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
23170 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
23180 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
23190 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
231a0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
231b0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
231c0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
231d0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
231e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
231f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
23200 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
23210 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
23220 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
23230 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
23240 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
23250 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57  f a table..** ^W
23260 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72  hen a table is r
23270 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b  eferenced by a [
23280 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63  SELECT] but no c
23290 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65  olumn values are
232a0 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72  .** extracted fr
232b0 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66  om that table (f
232c0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20  or example in a 
232d0 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53  query like.** "S
232e0 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46  ELECT count(*) F
232f0 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74  ROM tab") then t
23300 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  he [SQLITE_READ]
23310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
23320 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  back.** is invok
23330 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74  ed once for that
23340 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f   table with a co
23350 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69  lumn name that i
23360 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
23370 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  g..** ^If the ac
23380 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
23390 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
233a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
233b0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
233c0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
233d0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
233e0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
233f0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
23400 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
23410 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
23420 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
23430 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
23440 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
23450 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
23460 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
23470 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
23480 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
23490 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
234a0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
234b0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
234c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
234d0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
234e0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
234f0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
23500 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
23510 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
23520 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
23530 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
23540 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
23550 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
23560 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
23570 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
23580 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
23590 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
235a0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
235b0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
235c0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
235d0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
235e0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
235f0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
23600 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
23610 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
23620 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
23630 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
23640 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
23650 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
23660 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
23670 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
23680 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
23690 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
236a0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
236b0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
236c0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
236d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
236e0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
236f0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
23700 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
23710 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
23720 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
23730 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
23740 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
23750 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
23760 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
23770 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
23780 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
23790 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
237a0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
237b0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
237c0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
237d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
237e0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
237f0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
23800 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
23810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
23820 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
23830 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
23840 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
23850 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
23860 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
23870 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
23880 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
23890 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
238a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
238b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
238c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
238d0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
238e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
238f0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
23900 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
23910 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
23920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23930 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
23940 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
23950 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
23960 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
23970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
23980 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
23990 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
239a0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
239b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
239c0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
239d0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
239e0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
239f0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
23a00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
23a10 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
23a20 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
23a30 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
23a40 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
23a50 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
23a60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
23a70 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
23a80 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
23a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23aa0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
23ab0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
23ac0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
23ad0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
23ae0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
23af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
23b00 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
23b10 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
23b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
23b30 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
23b40 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
23b50 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
23b60 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
23b70 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
23b80 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
23b90 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
23ba0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
23bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
23bc0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
23bd0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
23be0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
23bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
23c00 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
23c10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
23c20 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
23c30 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
23c40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
23c50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
23c60 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
23c70 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
23c80 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
23c90 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
23ca0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
23cb0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
23cc0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
23cd0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
23ce0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
23cf0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
23d00 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
23d10 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23d20 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
23d30 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
23d40 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
23d50 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
23d60 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
23d70 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
23d80 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
23d90 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
23da0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
23db0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
23dc0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
23dd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
23de0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
23df0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
23e00 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
23e10 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23e20 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
23e30 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
23e40 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
23e50 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
23e60 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
23e70 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
23e80 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
23e90 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
23ea0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
23eb0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
23ec0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
23ed0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
23ee0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
23ef0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
23f00 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
23f10 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
23f20 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
23f30 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
23f40 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
23f50 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
23f60 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
23f70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
23f80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23f90 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
23fa0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
23fb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
23fc0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
23fd0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
23fe0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
23ff0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
24000 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
24010 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
24020 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
24030 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
24040 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
24050 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
24060 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
24070 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
24080 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
24090 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
240a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
240b0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
240c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
240d0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
240e0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
240f0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
24100 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
24110 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
24120 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
24130 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
24140 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
24150 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
24160 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
24170 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
24180 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
24190 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
241a0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
241b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
241c0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
241d0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
241e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
241f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24200 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
24210 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
24220 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
24230 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
24240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
24250 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
24260 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
24270 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
24280 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
24290 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
242a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
242b0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
242c0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
242d0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
242e0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
242f0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
24300 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
24310 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
24320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24330 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
24340 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
24350 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
24360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
24370 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
24380 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
24390 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
243a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
243b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
243c0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
243d0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
243e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
243f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24410 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
24420 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
24430 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
24440 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
24450 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
24460 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
24470 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
24480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
24490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
244a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
244b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
244c0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
244d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
244e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
244f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24500 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
24510 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
24520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24540 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
24550 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
24560 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
24570 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
24580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24590 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
245a0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
245b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
245c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
245d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
245e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
245f0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
24600 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24630 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
24640 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
24650 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
24660 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
24670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24680 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
24690 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
246a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
246b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
246c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
246d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
246e0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
246f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
24700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24720 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
24730 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
24740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
24750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24770 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
24780 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
24790 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
247a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
247b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
247c0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
247d0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
247e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
247f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24810 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
24820 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
24830 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
24840 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
24860 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
24870 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
24880 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
24890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
248a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
248b0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
248c0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
248d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
248e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
248f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
24900 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
24910 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
24920 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
24930 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
24940 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
24950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24960 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
24970 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
24980 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
24990 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
249a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
249b0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
249c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
249d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
249e0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
249f0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
24a00 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
24a10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24a20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24a30 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
24a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
24a50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
24a60 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
24a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24a80 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
24a90 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
24aa0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
24ab0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24ad0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
24ae0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
24af0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
24b00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24b20 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
24b30 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
24b40 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
24b50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
24b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24b70 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
24b80 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
24b90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
24ba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24bc0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
24bd0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
24be0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24bf0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24c10 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
24c20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
24c30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
24c40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
24c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24c60 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
24c70 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
24c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
24c90 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
24ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24cb0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
24cc0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
24cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
24ce0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
24cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
24d00 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
24d10 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
24d20 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
24d30 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
24d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
24d50 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
24d60 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
24d70 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
24d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
24d90 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
24da0 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
24db0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
24dc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
24dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
24de0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
24df0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
24e00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
24e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24e20 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
24e30 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
24e40 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24e50 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
24e60 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
24e70 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
24e80 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
24e90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
24ea0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
24eb0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
24ec0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
24ed0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
24ee0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
24ef0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
24f00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
24f10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
24f20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
24f30 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
24f40 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
24f50 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
24f60 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
24f70 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
24f80 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
24f90 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
24fa0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24fb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24fc0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
24fd0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
24fe0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
24ff0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
25000 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
25010 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
25020 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
25030 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
25040 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
25050 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
25060 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
25070 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
25080 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
25090 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
250a0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
250b0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
250c0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
250d0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
250e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
250f0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
25100 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
25110 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
25120 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
25130 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
25140 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
25150 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
25160 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
25170 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
25180 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
25190 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
251a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
251b0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
251c0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
251d0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
251e0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
251f0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
25200 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
25210 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
25220 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
25230 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
25240 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
25250 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
25260 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
25270 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
25280 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
25290 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
252a0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
252b0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
252c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
252d0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
252e0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
252f0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
25300 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
25310 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
25320 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
25330 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
25340 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
25350 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
25360 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
25370 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
25380 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
25390 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e 76 6f 6b  callback.  Invok
253a0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 5b 73  ing.** either [s
253b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
253c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  or [sqlite3_trac
253d0 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20 63 61 6e  e_v2()] will can
253e0 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72 6f 66 69  cel the.** profi
253f0 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a  le callback..*/.
25400 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
25410 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
25420 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
25430 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
25440 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
25450 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
25460 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
25470 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
25480 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
25490 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
254a0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
254b0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
254c0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
254d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
254e0 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
254f0 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
25500 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
25510 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
25520 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
25530 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
25540 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
25550 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
25560 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
25570 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
25580 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67  ogic.  The M arg
25590 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
255a0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
255b0 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52  M,X,P)] is an OR
255c0 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
255d0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
255e0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
255f0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
25600 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25610 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
25620 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
25630 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
25640 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
25650 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
25660 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
25670 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
25680 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
25690 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
256a0 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
256b0 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
256c0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
256d0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
256e0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
256f0 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
25700 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
25710 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
25720 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
25730 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
25740 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
25750 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
25760 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
25770 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
25780 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
25790 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
257a0 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
257b0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
257c0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
257d0 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
257e0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
257f0 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
25800 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25810 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
25820 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
25830 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25840 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
25850 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
25860 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
25870 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
25880 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
25890 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
258a0 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
258b0 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
258c0 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
258d0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
258e0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
258f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25900 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25910 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
25920 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
25930 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
25940 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
25950 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
25960 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
25970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25980 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
25990 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
259a0 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
259b0 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
259c0 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
259d0 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
259e0 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
259f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
25a00 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
25a10 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
25a20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
25a30 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
25a40 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
25a50 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
25a60 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
25a70 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
25a80 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
25a90 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
25aa0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25ab0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
25ac0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
25ad0 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
25ae0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
25af0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
25b00 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
25b10 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
25b20 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
25b30 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
25b40 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
25b50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
25b60 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
25b70 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
25b80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
25b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25ba0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
25bb0 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
25bc0 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
25bd0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
25be0 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
25bf0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
25c00 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
25c10 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
25c20 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
25c30 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
25c40 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
25c50 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
25c60 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
25c70 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
25c80 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
25c90 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
25ca0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25cb0 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
25cc0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25cd0 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
25ce0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
25cf0 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
25d00 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
25d10 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
25d20 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
25d30 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
25d40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
25d50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25d60 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
25d70 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
25d80 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
25d90 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
25da0 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
25db0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
25dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
25dd0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
25de0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
25df0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
25e00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
25e10 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
25e20 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
25e30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25e40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25e50 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
25e60 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
25e70 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
25e80 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
25e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
25ea0 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
25eb0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
25ec0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
25ed0 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
25ee0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
25ef0 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
25f00 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
25f10 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
25f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25f30 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
25f40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25f50 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
25f60 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25f70 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
25f80 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
25f90 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
25fa0 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
25fb0 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
25fc0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
25fd0 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
25fe0 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
25ff0 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
26000 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
26010 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
26020 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
26030 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
26040 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
26050 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
26060 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
26070 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
26080 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
26090 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
260a0 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
260b0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
260c0 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
260d0 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
260e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
260f0 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
26100 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
26110 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
26120 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
26130 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
26140 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
26150 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
26160 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
26170 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
26180 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
26190 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
261a0 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
261b0 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
261c0 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
261d0 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
261e0 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
261f0 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
26200 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
26210 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
26220 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
26230 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
26240 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
26250 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
26260 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
26270 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
26280 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
26290 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
262a0 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
262b0 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
262c0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
262d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
262e0 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
262f0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
26300 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
26310 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
26320 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
26330 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
26340 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
26350 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
26360 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
26370 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
26380 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
26390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
263a0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
263b0 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
263c0 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
263d0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
263e0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
263f0 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
26400 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
26410 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
26420 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
26430 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
26440 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73  e3_trace_v2(.  s
26450 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67  qlite3*,.  unsig
26460 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74  ned uMask,.  int
26470 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73  (*xCallback)(uns
26480 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64  igned,void*,void
26490 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  *,void*),.  void
264a0 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   *pCtx.);../*.**
264b0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
264c0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
264d0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
264e0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
264f0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
26500 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
26510 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
26520 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
26530 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
26540 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
26550 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
26560 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
26570 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
26580 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
26590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
265a0 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
265b0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
265c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
265d0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
265e0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
265f0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
26600 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
26610 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
26620 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
26630 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
26640 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
26650 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
26660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26670 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
26680 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
26690 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
266a0 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
266b0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
266c0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
266d0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
266e0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
266f0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
26700 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
26710 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
26720 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
26730 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
26740 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
26750 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
26760 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
26770 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
26780 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
26790 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
267a0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
267b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
267c0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
267d0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
267e0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
267f0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
26800 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
26810 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
26820 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
26830 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
26840 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
26850 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
26860 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
26870 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
26880 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
26890 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
268a0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
268b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
268c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
268d0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
268e0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
268f0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
26900 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
26910 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
26920 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
26930 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
26940 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
26950 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
26960 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
26970 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
26980 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
26990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
269a0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
269b0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
269c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
269d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
269e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
269f0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
26a00 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
26a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26a20 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
26a30 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
26a40 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
26a50 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
26a60 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
26a70 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
26a80 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
26a90 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
26aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
26ab0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
26ac0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
26ad0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
26ae0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
26af0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
26b00 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
26b10 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
26b20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
26b30 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
26b40 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
26b50 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
26b60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
26b70 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
26b80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
26b90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26ba0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
26bb0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
26bc0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
26bd0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
26be0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
26bf0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
26c00 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
26c10 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
26c20 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
26c30 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
26c40 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
26c50 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
26c60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
26c70 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
26c80 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
26c90 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
26ca0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
26cb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
26cc0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
26cd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
26ce0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
26cf0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
26d00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26d10 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
26d20 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
26d30 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
26d40 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
26d50 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
26d60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
26d70 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
26d80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
26d90 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
26da0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
26db0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
26dc0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
26dd0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
26de0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
26df0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
26e00 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
26e10 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
26e20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
26e30 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
26e40 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
26e50 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
26e60 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
26e70 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
26e80 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
26e90 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
26ea0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
26eb0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
26ec0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
26ed0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
26ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
26ef0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
26f00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
26f10 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
26f20 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
26f30 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
26f40 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
26f50 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
26f60 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
26f70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
26f80 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
26f90 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
26fa0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
26fb0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
26fc0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
26fd0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
26fe0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
26ff0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
27000 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
27010 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
27020 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
27030 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
27040 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
27050 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
27060 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
27070 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
27080 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
27090 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
270a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
270b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
270c0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
270d0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
270e0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
270f0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
27100 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
27110 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
27120 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
27130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
27140 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
27150 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
27160 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
27170 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
27180 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
27190 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
271a0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
271b0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
271c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
271d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
271e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
271f0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
27200 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
27210 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
27220 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
27230 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
27240 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
27250 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
27260 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
27270 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
27280 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27290 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
272a0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
272b0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
272c0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
272d0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
272e0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
272f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
27300 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
27310 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
27320 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
27330 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
27340 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
27350 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
27360 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
27370 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
27380 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
27390 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
273a0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
273b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
273c0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
273d0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
273e0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
273f0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
27400 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
27410 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
27420 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
27430 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
27440 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
27450 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
27460 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
27470 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
27480 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27490 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
274a0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
274b0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
274c0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
274d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
274e0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
274f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
27500 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
27510 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
27520 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
27530 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27540 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
27550 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
27560 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
27570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27580 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
27590 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
275a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
275b0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
275c0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
275d0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
275e0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
275f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
27600 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
27610 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
27620 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
27630 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
27640 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27650 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
27660 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
27670 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
27680 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
27690 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
276a0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
276b0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
276c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
276d0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
276e0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
276f0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
27700 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
27710 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
27720 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
27730 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
27740 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
27750 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
27760 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
27770 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
27780 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
27790 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
277a0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
277b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
277c0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
277d0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
277e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
277f0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
27800 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
27810 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
27820 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
27830 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
27840 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
27850 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
27860 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
27870 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
27880 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
27890 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
278a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
278b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
278c0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
278d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
278e0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
278f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27900 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
27910 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
27920 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
27930 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
27940 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
27950 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
27960 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
27970 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
27980 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
27990 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
279a0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
279b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
279c0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
279d0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
279e0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
279f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27a00 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
27a10 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
27a20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
27a30 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
27a40 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
27a50 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
27a60 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
27a70 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
27a80 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
27a90 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
27aa0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
27ab0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
27ac0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
27ad0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
27ae0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
27af0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
27b00 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
27b10 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
27b20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
27b30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
27b40 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
27b50 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
27b60 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
27b70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
27b80 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
27b90 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
27ba0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
27bb0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
27bc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
27bd0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
27be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27bf0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
27c00 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
27c10 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
27c20 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
27c30 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
27c40 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
27c50 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
27c60 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
27c70 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
27c80 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
27c90 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
27ca0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
27cb0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
27cc0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
27cd0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
27ce0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
27cf0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
27d00 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
27d10 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
27d20 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68  ** set in the th
27d30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
27d40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27d50 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
27d60 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
27d70 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
27d80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
27d90 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
27da0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
27db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
27dc0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
27dd0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
27de0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
27df0 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  on..** URI filen
27e00 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
27e10 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
27e20 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
27e30 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
27e40 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
27e50 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
27e60 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
27e70 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
27e80 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
27e90 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
27ea0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
27eb0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
27ec0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
27ed0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
27ee0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
27ef0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
27f00 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
27f10 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
27f20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
27f30 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
27f40 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
27f50 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
27f60 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
27f70 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
27f80 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
27f90 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
27fa0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
27fb0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
27fc0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
27fd0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
27fe0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
27ff0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
28000 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
28010 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
28020 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
28030 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28040 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
28050 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
28060 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
28070 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
28080 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
28090 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
280a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
280b0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
280c0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
280d0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
280e0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
280f0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
28100 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
28110 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
28120 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
28130 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
28140 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
28150 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
28160 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
28170 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
28180 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
28190 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
281a0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
281b0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
281c0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
281d0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
281e0 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
281f0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
28200 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
28210 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
28220 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
28230 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
28240 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
28250 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
28260 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
28270 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
28280 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
28290 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
282a0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
282b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
282c0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
282d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
282e0 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
282f0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
28300 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
28310 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
28320 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
28330 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
28340 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
28350 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
28360 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
28370 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
28380 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
28390 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
283a0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
283b0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
283c0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
283d0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
283e0 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
283f0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
28400 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
28410 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
28420 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
28430 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
28440 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
28450 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
28460 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
28470 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
28480 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
28490 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
284a0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
284b0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
284c0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
284d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
284e0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
284f0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
28500 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
28510 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
28520 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
28530 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
28540 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
28550 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
28560 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
28570 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
28580 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
28590 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
285a0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
285b0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
285c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
285d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
285e0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
285f0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
28600 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
28610 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
28620 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
28630 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
28640 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
28650 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
28660 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
28670 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
28680 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
28690 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
286a0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
286b0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
286c0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
286d0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
286e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
286f0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
28700 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
28710 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
28720 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
28730 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
28740 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
28750 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
28760 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
28770 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
28780 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
28790 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
287a0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
287b0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
287c0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
287d0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
287e0 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
287f0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
28800 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
28810 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
28820 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
28830 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
28840 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
28850 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
28860 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
28870 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
28880 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
28890 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
288a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
288b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
288c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
288d0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
288e0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
288f0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
28900 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
28910 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
28920 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
28930 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
28940 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28950 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
28960 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
28970 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
28980 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
28990 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
289a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
289b0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
289c0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
289d0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
289e0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
289f0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
28a00 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
28a10 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
28a20 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
28a30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
28a40 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
28a50 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
28a60 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
28a70 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
28a80 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
28a90 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
28aa0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
28ab0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
28ac0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
28ad0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
28ae0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
28af0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
28b00 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
28b10 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
28b20 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
28b30 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
28b40 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
28b50 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
28b60 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
28b70 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
28b80 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
28b90 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
28ba0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
28bb0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
28bc0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
28bd0 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
28be0 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
28bf0 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
28c00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
28c10 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
28c20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
28c30 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
28c40 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
28c50 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
28c60 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
28c70 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
28c80 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
28c90 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
28ca0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
28cb0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
28cc0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
28cd0 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
28ce0 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
28cf0 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
28d00 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
28d10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
28d20 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
28d30 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
28d40 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
28d50 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
28d60 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
28d70 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
28d80 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
28d90 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
28da0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
28db0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
28dc0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
28dd0 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
28de0 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
28df0 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
28e00 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
28e10 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
28e20 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
28e30 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
28e40 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
28e50 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
28e60 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
28e70 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
28e80 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
28e90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
28ea0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
28eb0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
28ec0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
28ed0 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
28ee0 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
28ef0 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
28f00 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
28f10 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
28f20 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
28f30 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
28f40 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
28f50 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
28f60 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
28f70 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
28f80 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
28f90 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
28fa0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
28fb0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
28fc0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
28fd0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
28fe0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
28ff0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
29000 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
29010 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
29020 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
29030 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
29040 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
29050 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
29060 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
29070 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
29080 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
29090 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
290a0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
290b0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
290c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
290d0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
290e0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
290f0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
29100 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
29110 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
29120 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
29130 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
29140 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
29150 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
29160 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
29170 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
29180 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
29190 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
291a0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
291b0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
291c0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
291d0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
291e0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
291f0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
29200 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29210 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
29220 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
29230 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
29240 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
29250 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
29260 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
29270 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
29280 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
29290 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
292a0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
292b0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
292c0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
292d0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
292e0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
292f0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
29300 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
29310 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
29320 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
29330 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
29340 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
29350 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
29360 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
29370 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
29380 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
29390 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
293a0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
293b0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
293c0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
293d0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
293e0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
293f0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
29400 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
29410 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
29420 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
29430 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
29440 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
29450 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
29460 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
29470 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
29480 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
29490 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
294a0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
294b0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
294c0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
294d0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
294e0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
294f0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
29500 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
29510 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
29520 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
29530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
29540 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
29550 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
29560 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
29570 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
29580 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
29590 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
295a0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
295b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
295c0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
295d0 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
295e0 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
295f0 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
29600 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
29610 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
29620 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
29630 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
29640 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
29650 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
29660 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
29670 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
29680 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
29690 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
296a0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
296b0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
296c0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
296d0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
296e0 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
296f0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
29700 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
29710 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
29720 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
29730 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
29740 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
29750 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
29760 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
29770 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
29780 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
29790 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
297a0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
297b0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
297c0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
297d0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
297e0 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
297f0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
29800 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
29810 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
29820 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
29830 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
29840 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
29850 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
29860 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
29870 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
29880 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
29890 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
298a0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
298b0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
298c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
298d0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
298e0 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
298f0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
29900 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
29910 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
29920 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
29930 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
29940 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
29950 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
29960 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
29970 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
29980 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
29990 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
299a0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
299b0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
299c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
299d0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
299e0 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
299f0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
29a00 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
29a10 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
29a20 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
29a30 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
29a40 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
29a50 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
29a60 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
29a70 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
29a80 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
29a90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
29aa0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
29ab0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
29ac0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
29ad0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
29ae0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
29af0 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
29b00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29b10 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
29b20 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
29b30 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
29b40 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
29b50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
29b60 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
29b70 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
29b80 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
29b90 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
29ba0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
29bb0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
29bc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
29bd0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
29be0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
29bf0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
29c00 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
29c10 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
29c20 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
29c30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
29c40 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
29c50 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
29c60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
29c70 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
29c80 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
29c90 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
29ca0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
29cb0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
29cc0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
29cd0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
29ce0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
29cf0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
29d00 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
29d10 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
29d20 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
29d30 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
29d40 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
29d50 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
29d60 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
29d70 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
29d80 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
29d90 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
29da0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
29db0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
29dc0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
29dd0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
29de0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
29df0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
29e00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
29e10 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
29e20 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
29e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29e40 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
29e50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
29e60 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
29e70 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
29e80 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
29e90 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
29ea0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
29eb0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
29ec0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
29ed0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
29ee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
29ef0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
29f00 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
29f10 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
29f20 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
29f30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
29f40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
29f50 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
29f60 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
29f70 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
29f80 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
29f90 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
29fa0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
29fb0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
29fc0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
29fd0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
29fe0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
29ff0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
2a000 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
2a010 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
2a020 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
2a030 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
2a040 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
2a050 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
2a060 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
2a070 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
2a080 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
2a090 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
2a0a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
2a0b0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
2a0c0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
2a0d0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
2a0e0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
2a0f0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a100 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
2a110 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
2a120 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
2a130 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
2a140 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
2a150 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
2a160 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
2a170 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
2a180 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
2a190 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
2a1a0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
2a1b0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
2a1c0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
2a1d0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
2a1e0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
2a1f0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
2a200 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
2a210 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
2a220 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
2a230 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
2a240 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
2a250 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
2a260 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
2a270 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
2a280 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
2a290 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
2a2a0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
2a2b0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
2a2c0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
2a2d0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
2a2e0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
2a2f0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
2a300 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
2a310 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
2a320 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
2a330 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
2a340 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2a350 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
2a360 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
2a370 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
2a380 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
2a390 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
2a3a0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
2a3b0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
2a3c0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
2a3d0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
2a3e0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
2a3f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2a400 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
2a410 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
2a420 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
2a430 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
2a440 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
2a450 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
2a460 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
2a470 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
2a480 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
2a490 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
2a4a0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
2a4b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
2a4c0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
2a4d0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
2a4e0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
2a4f0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
2a500 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
2a510 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
2a520 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 55  **.** See the [U
2a530 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 64 6f 63  RI filename] doc
2a540 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2a550 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2a560 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ation..*/.const 
2a570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
2a580 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
2a590 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
2a5a0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
2a5b0 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
2a5c0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2a5d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
2a5e0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
2a5f0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
2a600 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
2a610 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
2a620 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
2a630 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a640 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2a650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a660 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
2a670 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45  d Messages.** ME
2a680 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2a690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2a6a0 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
2a6b0 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
2a6c0 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b  iated with .** [
2a6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a6e0 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74  ion] D failed, t
2a6f0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2a700 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72  errcode(D) inter
2a710 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
2a720 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
2a730 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
2a740 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2a750 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20  de] for that.** 
2a760 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68  API call..** ^Th
2a770 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
2a780 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
2a790 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
2a7a0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
2a7b0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
2a7c0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
2a7d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2a7e0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
2a7f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2a800 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
2a810 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  ed..**.** The va
2a820 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2a830 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
2a840 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  () and/or.** sql
2a850 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2a860 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20 63 68  rcode() might ch
2a870 61 6e 67 65 20 77 69 74 68 20 65 61 63 68 20 41  ange with each A
2a880 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65  PI call..** Exce
2a890 70 74 2c 20 74 68 65 72 65 20 61 72 65 20 73 6f  pt, there are so
2a8a0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 68  me interfaces th
2a8b0 61 74 20 61 72 65 20 67 75 61 72 61 6e 74 65 65  at are guarantee
2a8c0 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20 63 68  d to never.** ch
2a8d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 6f  ange the value o
2a8e0 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  f the error code
2a8f0 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63 6f 64  .  The error-cod
2a900 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a 2a 20  e preserving.** 
2a910 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 3a 0a  interfaces are:.
2a920 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2a930 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  i> sqlite3_errco
2a940 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  de().** <li> sql
2a950 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2a960 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20  rcode().** <li> 
2a970 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2a980 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  .** <li> sqlite3
2a990 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20 3c  _errmsg16().** <
2a9a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  /ul>.**.** ^The 
2a9b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2a9c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
2a9d0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
2a9e0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
2a9f0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
2aa00 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2aa10 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
2aa20 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
2aa30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
2aa40 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
2aa50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2aa60 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
2aa70 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
2aa80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2aa90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2aaa0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
2aab0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
2aac0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
2aad0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
2aae0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
2aaf0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
2ab00 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
2ab10 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
2ab20 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
2ab30 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
2ab40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab50 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
2ab60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2ab70 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
2ab80 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
2ab90 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
2aba0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
2abb0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
2abc0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
2abd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
2abe0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
2abf0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
2ac00 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
2ac10 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
2ac20 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
2ac30 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
2ac40 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
2ac50 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
2ac60 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
2ac70 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
2ac80 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
2ac90 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
2aca0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
2acb0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
2acc0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
2acd0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
2ace0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2acf0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
2ad00 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
2ad10 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
2ad20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
2ad30 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
2ad40 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
2ad50 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
2ad60 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
2ad70 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
2ad80 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
2ad90 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
2ada0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
2adb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2adc0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
2add0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
2ade0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
2adf0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
2ae00 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
2ae10 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
2ae20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
2ae30 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
2ae40 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
2ae50 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
2ae60 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
2ae70 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
2ae80 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
2ae90 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
2aea0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
2aeb0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
2aec0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
2aed0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
2aee0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
2aef0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
2af00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
2af10 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
2af20 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
2af30 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
2af40 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
2af50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2af60 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
2af70 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
2af80 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
2af90 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2afa0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2afb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
2afc0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
2afd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
2afe0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
2aff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b000 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
2b010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b020 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
2b030 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
2b040 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
2b050 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
2b060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b070 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
2b080 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
2b090 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
2b0a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
2b0b0 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
2b0c0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
2b0d0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
2b0e0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
2b0f0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
2b100 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
2b110 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
2b120 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
2b130 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
2b140 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
2b150 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
2b160 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
2b170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b180 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
2b190 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
2b1a0 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
2b1b0 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
2b1c0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
2b1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b1e0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
2b1f0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
2b200 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
2b210 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b220 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
2b230 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
2b240 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
2b250 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
2b260 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b270 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
2b280 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2b290 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
2b2a0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
2b2b0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
2b2c0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2b2d0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
2b2e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2b2f0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
2b300 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2b310 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
2b320 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
2b330 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
2b340 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b350 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2b360 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
2b370 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
2b380 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
2b390 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
2b3a0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2b3b0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
2b3c0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
2b3d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2b3e0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
2b3f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2b400 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
2b410 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
2b420 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
2b430 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
2b440 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
2b450 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
2b460 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
2b470 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
2b480 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
2b490 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
2b4a0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
2b4b0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
2b4c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b4d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
2b4e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b4f0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
2b500 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
2b510 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
2b520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2b530 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
2b540 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2b550 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
2b560 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
2b570 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
2b580 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
2b590 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2b5a0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
2b5b0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
2b5c0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
2b5d0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
2b5e0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
2b5f0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
2b600 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
2b610 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
2b620 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
2b630 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
2b640 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
2b650 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
2b660 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
2b670 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
2b680 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
2b690 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
2b6a0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
2b6b0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
2b6c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
2b6d0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
2b6e0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
2b6f0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
2b700 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
2b710 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
2b720 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
2b730 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
2b740 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
2b750 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
2b760 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
2b770 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
2b780 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2b790 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
2b7a0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
2b7b0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
2b7c0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
2b7d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2b7e0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
2b7f0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
2b800 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
2b810 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
2b820 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
2b830 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
2b840 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
2b850 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2b860 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
2b870 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
2b880 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
2b890 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
2b8a0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
2b8b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
2b8c0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
2b8d0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
2b8e0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
2b8f0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
2b900 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
2b910 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
2b920 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
2b930 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
2b940 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
2b950 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
2b960 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
2b970 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
2b980 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
2b990 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
2b9a0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
2b9b0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
2b9c0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
2b9d0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
2b9e0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
2b9f0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
2ba00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
2ba10 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
2ba20 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
2ba30 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
2ba40 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
2ba50 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
2ba60 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
2ba70 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
2ba80 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
2ba90 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
2baa0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
2bab0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
2bac0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
2bad0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
2bae0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2baf0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
2bb00 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
2bb10 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
2bb20 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
2bb30 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
2bb40 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
2bb50 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
2bb60 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
2bb70 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
2bb80 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
2bb90 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
2bba0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
2bbb0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
2bbc0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
2bbd0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2bbe0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
2bbf0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
2bc00 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
2bc10 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
2bc20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
2bc30 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
2bc40 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
2bc50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
2bc60 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
2bc70 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
2bc80 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2bc90 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
2bca0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
2bcb0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
2bcc0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
2bcd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bce0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
2bcf0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
2bd00 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
2bd10 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
2bd20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
2bd30 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
2bd40 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
2bd50 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
2bd60 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
2bd70 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
2bd80 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
2bd90 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
2bda0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2bdb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2bdc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
2bdd0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
2bde0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
2bdf0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
2be00 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
2be10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2be20 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2be30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2be40 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2be50 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2be60 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
2be70 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
2be80 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
2be90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bea0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
2beb0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
2bec0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
2bed0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2bee0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2bef0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
2bf00 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
2bf10 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
2bf20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
2bf30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2bf40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2bf50 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
2bf60 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
2bf70 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
2bf80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2bf90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2bfa0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2bfb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2bfc0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
2bfd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2bfe0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
2bff0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
2c000 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
2c010 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c020 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2c030 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
2c040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2c050 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
2c060 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c070 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
2c080 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
2c090 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
2c0a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
2c0b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c0c0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
2c0d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2c0e0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
2c0f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2c100 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
2c110 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
2c120 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
2c130 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
2c140 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
2c150 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
2c160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c170 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
2c180 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
2c190 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
2c1a0 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
2c1b0 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
2c1c0 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
2c1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c1e0 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
2c1f0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
2c200 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
2c210 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c220 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
2c230 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c240 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2c250 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c260 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2c270 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
2c280 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
2c290 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2c2a0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2c2b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c2c0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
2c2d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c2e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c2f0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
2c300 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
2c310 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
2c320 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2c330 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
2c340 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2c350 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2c360 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
2c370 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
2c390 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
2c3a0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
2c3b0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
2c3c0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
2c3d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2c3e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2c3f0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
2c400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2c410 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
2c420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c430 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
2c440 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
2c450 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
2c460 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
2c470 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2c480 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
2c490 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c4a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2c4b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2c4c0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2c4d0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
2c4e0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
2c4f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c500 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2c510 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
2c520 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2c530 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
2c540 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c550 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
2c560 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
2c570 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
2c580 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
2c590 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
2c5a0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
2c5b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
2c5c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
2c5d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2c5e0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
2c5f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
2c600 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
2c610 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2c620 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c630 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
2c640 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2c650 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c660 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2c670 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2c680 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c690 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2c6a0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2c6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c6c0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2c6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2c6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c6f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2c700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2c710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c720 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2c730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2c740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c750 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2c760 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2c770 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2c780 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2c790 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2c7a0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2c7b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2c7c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2c7d0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2c7e0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2c7f0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2c800 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
2c810 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c  3REF: Prepare Fl
2c820 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
2c830 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2c840 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74   various flags t
2c850 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65  hat can be passe
2c860 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46  d into.** "prepF
2c870 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20  lags" parameter 
2c880 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2c890 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e  prepare_v3()] an
2c8a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
2c8b0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
2c8c0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  terfaces..**.** 
2c8d0 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65  New flags may be
2c8e0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
2c8f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
2c900 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ite..**.** <dl>.
2c910 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2c920 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d  ARE_PERSISTENT]]
2c930 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52   ^(<dt>SQLITE_PR
2c940 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2c950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c960 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2c970 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20  PERSISTENT flag 
2c980 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65  is a hint to the
2c990 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a   query planner.*
2c9a0 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  * that the prepa
2c9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69  red statement wi
2c9c0 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20 66  ll be retained f
2c9d0 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61  or a long time a
2c9e0 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72  nd.** probably r
2c9f0 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73  eused many times
2ca00 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69  .)^ ^Without thi
2ca10 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33  s flag, [sqlite3
2ca20 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a  _prepare_v3()].*
2ca30 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  * and [sqlite3_p
2ca40 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61  repare16_v3()] a
2ca50 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20 70  ssume that the p
2ca60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca70 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73  t will .** be us
2ca80 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20  ed just once or 
2ca90 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69  at most a few ti
2caa0 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73  mes and then des
2cab0 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20  troyed using.** 
2cac0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2cad0 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20  e()] relatively 
2cae0 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e  soon. The curren
2caf0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2cb00 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73   acts.** on this
2cb10 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e   hint by avoidin
2cb20 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f  g the use of [lo
2cb30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20  okaside memory] 
2cb40 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20  so as not to.** 
2cb50 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69  deplete the limi
2cb60 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f  ted store of loo
2cb70 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46  kaside memory. F
2cb80 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
2cb90 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20  f.** SQLite may 
2cba0 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  act on this hint
2cbb0 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a   differently..**
2cbc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2cbd0 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d  PARE_NORMALIZE]]
2cbe0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50   <dt>SQLITE_PREP
2cbf0 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64  ARE_NORMALIZE</d
2cc00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
2cc10 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52  LITE_PREPARE_NOR
2cc20 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 73 20 61  MALIZE flag is a
2cc30 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66 6c 61   no-op. This fla
2cc40 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 65 20  g used.** to be 
2cc50 72 65 71 75 69 72 65 64 20 66 6f 72 20 61 6e 79  required for any
2cc60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cc70 65 6e 74 20 74 68 61 74 20 77 61 6e 74 65 64 20  ent that wanted 
2cc80 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73  to use the.** [s
2cc90 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2cca0 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61  d_sql()] interfa
2ccb0 63 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68  ce.  However, th
2ccc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 6f  e.** [sqlite3_no
2ccd0 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20  rmalized_sql()] 
2cce0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 77  interface is now
2ccf0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 61 6c   available to al
2cd00 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  l.** prepared st
2cd10 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 61 72 64  atements, regard
2cd20 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2cd30 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 73 65 20  or not they use 
2cd40 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a 2a 2a  this.** flag..**
2cd50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2cd60 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d 20 3c  PARE_NO_VTAB]] <
2cd70 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52  dt>SQLITE_PREPAR
2cd80 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e 0a 2a  E_NO_VTAB</dt>.*
2cd90 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2cda0 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42  _PREPARE_NO_VTAB
2cdb0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
2cdc0 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a   SQL compiler.**
2cdd0 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 20 65 72   to return an er
2cde0 72 6f 72 20 28 65 72 72 6f 72 20 63 6f 64 65 20  ror (error code 
2cdf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 20 69 66  SQLITE_ERROR) if
2ce00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
2ce10 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72 74 75  ses.** any virtu
2ce20 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f  al tables..** </
2ce30 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2ce40 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2ce50 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2ce60 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
2ce70 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  ne SQLITE_PREPAR
2ce80 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20 20  E_NORMALIZE     
2ce90 20 20 20 20 20 20 20 20 20 20 30 78 30 32 0a 23            0x02.#
2cea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
2ceb0 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 20 20  EPARE_NO_VTAB   
2cec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
2ced0 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  04../*.** CAPI3R
2cee0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
2cef0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2cf00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2cf10 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
2cf20 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
2cf30 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
2cf40 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
2cf50 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
2cf60 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61  ecute an SQL sta
2cf70 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20  tement, it must 
2cf80 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
2cf90 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
2cfa0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
2cfb0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
2cfc0 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20   routines.  Or, 
2cfd0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
2cfe0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2cff0 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f  * are constructo
2d000 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  rs for the [prep
2d010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d020 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  object..**.** Th
2d030 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74  e preferred rout
2d040 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73  ine to use is [s
2d050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d060 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  2()].  The.** [s
2d070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2d080 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c  ] interface is l
2d090 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64  egacy and should
2d0a0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20   be avoided..** 
2d0b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d0c0 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78  _v3()] has an ex
2d0d0 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20  tra "prepFlags" 
2d0e0 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75  option that is u
2d0f0 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69  sed.** for speci
2d100 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  al purposes..**.
2d110 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  ** The use of th
2d120 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63  e UTF-8 interfac
2d130 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c  es is preferred,
2d140 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65   as SQLite curre
2d150 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c  ntly.** does all
2d160 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55   parsing using U
2d170 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31  TF-8.  The UTF-1
2d180 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  6 interfaces are
2d190 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20   provided.** as 
2d1a0 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20  a convenience.  
2d1b0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2d1c0 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f  faces work by co
2d1d0 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20  nverting the.** 
2d1e0 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20  input text into 
2d1f0 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f  UTF-8, then invo
2d200 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70  king the corresp
2d210 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74  onding UTF-8 int
2d220 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
2d230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d240 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
2d250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d260 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
2d270 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
2d280 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2d290 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2d2b0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
2d2c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
2d2d0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
2d2e0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
2d2f0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
2d300 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
2d310 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
2d320 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
2d330 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2d340 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
2d350 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
2d360 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
2d370 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2d380 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  e(), sqlite3_pre
2d390 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  pare_v2(),.** an
2d3a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2d3b0 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v3().** interf
2d3c0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
2d3d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2d3e0 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33  are16(), sqlite3
2d3f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2d400 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2d410 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75  prepare16_v3() u
2d420 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
2d430 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
2d440 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74  rgument is negat
2d450 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ive, then zSql i
2d460 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
2d470 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
2d480 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
2d490 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65  Byte is positive
2d4a0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
2d4b0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2d4c0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
2d4d0 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69  ql.  ^If nByte i
2d4e0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20  s zero, then no 
2d4f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2d500 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74  ement is generat
2d510 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
2d520 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20  ller knows that 
2d530 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
2d540 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
2d550 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74  nated, then.** t
2d560 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20  here is a small 
2d570 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
2d580 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67  ntage to passing
2d590 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
2d5a0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74  ter that.** is t
2d5b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d5c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
2d5d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
2d5e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
2d5f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ul-terminator..*
2d600 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
2d610 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
2d620 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
2d630 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
2d640 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
2d650 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
2d660 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
2d670 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
2d680 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d690 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
2d6a0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
2d6b0 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
2d6c0 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
2d6d0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
2d6e0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
2d6f0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
2d700 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
2d710 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
2d720 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
2d730 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2d740 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
2d750 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2d760 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
2d770 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
2d780 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
2d790 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
2d7a0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
2d7b0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
2d7c0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
2d7d0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
2d7e0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
2d7f0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
2d800 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
2d810 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
2d820 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
2d830 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
2d840 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
2d850 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2d860 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2d870 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
2d880 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
2d890 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
2d8a0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
2d8b0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2d8c0 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
2d8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d8e0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
2d8f0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2d900 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
2d910 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
2d920 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2d930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2d940 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d950 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2d960 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33  re_v3(), sqlite3
2d970 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2d980 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2d990 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69  prepare16_v3() i
2d9a0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
2d9b0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2d9c0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a  l new programs..
2d9d0 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74  ** The older int
2d9e0 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33  erfaces (sqlite3
2d9f0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
2da00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2da10 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69  ()).** are retai
2da20 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
2da30 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2da40 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2da50 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2da60 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69  * ^In the "vX" i
2da70 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2da80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da90 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2daa0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2dab0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2dac0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2dad0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2dae0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2daf0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2db00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2db10 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2db20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2db30 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2db40 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2db50 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2db60 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2db70 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2db80 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2db90 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2dba0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2dbb0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2dbc0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2dbd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2dbe0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2dbf0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2dc00 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2dc10 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2dc20 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2dc30 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2dc40 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2dc50 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2dc60 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2dc70 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2dc80 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2dc90 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2dca0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2dcb0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2dcc0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2dcd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2dce0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2dcf0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2dd00 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2dd10 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2dd20 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2dd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2dd40 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2dd50 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2dd60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2dd70 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2dd80 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2dd90 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2dda0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2ddb0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2ddc0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2ddd0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2dde0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2ddf0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2de00 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2de10 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2de20 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2de30 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2de40 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2de50 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2de60 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2de70 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2de80 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2de90 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2dea0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2deb0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2dec0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2ded0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2dee0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2def0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2df00 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2df10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2df20 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2df30 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2df40 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2df50 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2df60 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2df70 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2df80 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2df90 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2dfa0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2dfb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2dfc0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2dfd0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2dfe0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2dff0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2e000 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2e010 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2e020 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2e030 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2e040 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2e050 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2e060 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2e070 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2e080 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2e090 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2e0a0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2e0b0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2e0c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2e0d0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2e0e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2e0f0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2e100 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
2e110 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71  ol>.**.** <p>^sq
2e120 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2e130 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20  () differs from 
2e140 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e150 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76  v2() only in hav
2e160 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61  ing.** the extra
2e170 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2e180 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61  eter, which is a
2e190 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69   bit array consi
2e1a0 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72  sting of zero or
2e1b0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
2e1c0 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2e1d0 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54  PERSISTENT|SQLIT
2e1e0 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61  E_PREPARE_*] fla
2e1f0 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  gs.  ^The.** sql
2e200 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2e210 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
2e220 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
2e230 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33  me as.** sqlite3
2e240 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69  _prepare_v3() wi
2e250 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c  th a zero prepFl
2e260 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ags parameter..*
2e270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
2e280 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2e290 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e2a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2e2b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2e2c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2e2d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2e2e0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2e2f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2e300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e310 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2e320 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2e330 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2e340 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2e350 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2e360 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e370 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2e380 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2e390 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2e3a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2e3b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2e3c0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2e3d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e3e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2e3f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2e400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2e410 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2e420 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2e430 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2e440 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2e450 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2e460 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2e470 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2e480 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2e490 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2e4a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2e4b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2e4c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2e4d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2e4e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2e4f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2e500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e510 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2e520 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2e530 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2e540 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2e550 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2e560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2e570 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2e580 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2e590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2e5a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2e5b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2e5c0 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  .  unsigned int 
2e5d0 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65  prepFlags, /* Ze
2e5e0 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54  ro or more SQLIT
2e5f0 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73  E_PREPARE_ flags
2e600 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2e610 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2e620 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2e630 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e640 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2e650 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2e660 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2e670 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2e680 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e690 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2e6a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2e6b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2e6c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e6d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2e6e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2e6f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2e700 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2e710 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2e720 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2e730 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2e740 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2e750 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2e760 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2e770 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2e780 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2e790 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2e7a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2e7b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2e7c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2e7d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e7e0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2e7f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2e800 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2e810 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2e820 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2e830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2e840 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2e850 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2e860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2e870 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2e880 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2e890 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2e8a0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2e8b0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2e8c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2e8d0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2e8e0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2e8f0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2e900 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2e910 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2e920 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73  repare16_v3(.  s
2e930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e940 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2e950 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2e960 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2e970 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2e980 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2e990 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2e9a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2e9b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2e9c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2e9d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2e9e0 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2e9f0 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2ea00 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2ea10 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2ea20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ea30 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ea40 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ea50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2ea60 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2ea70 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ea80 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2ea90 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2eaa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eab0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2eac0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2ead0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2eae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2eaf0 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2eb00 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2eb10 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2eb20 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2eb30 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2eb40 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2eb50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2eb60 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2eb70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2eb80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2eb90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2eba0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
2ebb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ebc0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2ebd0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
2ebe0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ebf0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2ec00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ec10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ec20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2ec30 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2ec40 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2ec50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ec60 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2ec70 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2ec80 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  anded..** ^The s
2ec90 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2eca0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2ecb0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ecc0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2ecd0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2ece0 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61 6c 69  ning the normali
2ecf0 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  zed SQL text of 
2ed00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ed10 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20 73 65  nt P.  The.** se
2ed20 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74 6f 20  mantics used to 
2ed30 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51 4c 20  normalize a SQL 
2ed40 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 75 6e  statement are un
2ed50 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 73 75  specified and su
2ed60 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e  bject.** to chan
2ed70 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69 6d 75  ge.  At a minimu
2ed80 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c 75 65  m, literal value
2ed90 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c 61 63  s will be replac
2eda0 65 64 20 77 69 74 68 20 73 75 69 74 61 62 6c 65  ed with suitable
2edb0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2edc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2edd0 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70  ample, if a prep
2ede0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2edf0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
2ee00 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20  the SQL.** text 
2ee10 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2ee20 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65  z" and if parame
2ee30 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e  ter $abc is boun
2ee40 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34  d to integer 234
2ee50 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74  5.** and paramet
2ee60 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75  er :xyz is unbou
2ee70 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  nd, then sqlite3
2ee80 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75  _sql() will retu
2ee90 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  rn.** the origin
2eea0 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45  al string, "SELE
2eeb0 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75  CT $abc,:xyz" bu
2eec0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  t sqlite3_expand
2eed0 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c  ed_sql().** will
2eee0 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20   return "SELECT 
2eef0 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a  2345,NULL".)^.**
2ef00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ef10 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2ef20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ef30 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  s NULL if insuff
2ef40 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a  icient memory.**
2ef50 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
2ef60 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
2ef70 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75  , or if the resu
2ef80 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  lt would exceed 
2ef90 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d  the.** the maxim
2efa0 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68  um string length
2efb0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2efc0 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  he [SQLITE_LIMIT
2efd0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20  _LENGTH]..**.** 
2efe0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  ^The [SQLITE_TRA
2eff0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
2f000 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2f010 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69  on limits the si
2f020 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70  ze of.** bound p
2f030 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69  arameter expansi
2f040 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ons.  ^The [SQLI
2f050 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63  TE_OMIT_TRACE] c
2f060 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
2f070 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c  ption causes sql
2f080 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2f090 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65  l() to always re
2f0a0 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  turn NULL..**.**
2f0b0 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20 72 65   ^The strings re
2f0c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2f0d0 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73 71 6c  3_sql(P) and sql
2f0e0 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f  ite3_normalized_
2f0f0 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20 6d 61  sql(P).** are ma
2f100 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2f110 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61 74 69  and are automati
2f120 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2f130 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2f140 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f150 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65  nalized..** ^The
2f160 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2f170 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61   by sqlite3_expa
2f180 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20  nded_sql(P), on 
2f190 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a  the other hand,.
2f1a0 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  ** is obtained f
2f1b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f1c0 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20  loc()] and must 
2f1d0 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61  be free by the a
2f1e0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79  pplication.** by
2f1f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
2f200 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2f210 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2f220 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
2f230 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f240 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
2f250 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2f260 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f270 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2f280 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2f290 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2f2a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2f2b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2f2c0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2f2d0 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2f2e0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2f2f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f300 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f310 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2f320 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2f330 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2f340 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2f350 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2f360 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f370 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2f380 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2f390 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2f3a0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2f3b0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2f3c0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2f3d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f3e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2f3f0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2f400 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2f410 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2f420 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2f430 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2f440 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2f450 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2f460 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2f470 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2f480 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2f490 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2f4a0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2f4b0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2f4c0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2f4d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2f4e0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2f4f0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2f500 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2f510 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2f520 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2f530 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2f540 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2f550 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2f560 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2f570 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2f580 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2f590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2f5a0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2f5b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2f5c0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2f5d0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2f5e0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2f5f0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2f600 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2f610 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2f620 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2f630 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2f640 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2f650 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2f660 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2f670 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2f680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2f690 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2f6a0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2f6b0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2f6c0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2f6d0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2f6e0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2f6f0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2f700 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2f710 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2f720 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2f730 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2f740 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2f750 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2f760 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2f770 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2f780 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2f790 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2f7a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2f7b0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2f7c0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2f7d0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2f7e0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2f7f0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2f800 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2f810 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2f820 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2f830 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f840 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2f850 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2f860 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2f870 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2f880 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2f890 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2f8a0 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2f8b0 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2f8c0 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2f8d0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2f8e0 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2f8f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2f900 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2f910 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2f920 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2f930 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f940 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f950 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f960 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 54 68  PI3REF: Query Th
2f970 65 20 45 58 50 4c 41 49 4e 20 53 65 74 74 69 6e  e EXPLAIN Settin
2f980 67 20 46 6f 72 20 41 20 50 72 65 70 61 72 65 64  g For A Prepared
2f990 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2f9a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f9b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2f9c0 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70  lite3_stmt_isexp
2f9d0 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 66 61 63  lain(S) interfac
2f9e0 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
2f9f0 68 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  he.** prepared s
2fa00 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e  tatement S is an
2fa10 20 45 58 50 4c 41 49 4e 20 73 74 61 74 65 6d 65   EXPLAIN stateme
2fa20 6e 74 2c 20 6f 72 20 32 20 69 66 20 74 68 65 0a  nt, or 2 if the.
2fa30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  ** statement S i
2fa40 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 51 55 45  s an EXPLAIN QUE
2fa50 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e 54 68 65  RY PLAN..** ^The
2fa60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73   sqlite3_stmt_is
2fa70 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72  explain(S) inter
2fa80 66 61 63 65 20 72 65 74 75 72 6e 73 20 30 20 69  face returns 0 i
2fa90 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20 6f 72 64  f S is.** an ord
2faa0 69 6e 61 72 79 20 73 74 61 74 65 6d 65 6e 74 20  inary statement 
2fab0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
2fac0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2fad0 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e  3_stmt_isexplain
2fae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2faf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2fb00 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2fb10 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2fb20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2fb30 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2fb40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2fb50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fb60 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2fb70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fb80 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2fb90 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2fba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fbb0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2fbc0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2fbd0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2fbe0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2fbf0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2fc00 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2fc10 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2fc20 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2fc30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2fc40 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2fc50 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2fc60 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2fc70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2fc80 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2fc90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fca0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2fcb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2fcc0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2fcd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2fce0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2fcf0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2fd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fd10 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2fd20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2fd30 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2fd40 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2fd50 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2fd60 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2fd70 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2fd80 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2fd90 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2fda0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2fdb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fdc0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2fdd0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2fde0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2fdf0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2fe00 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2fe10 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2fe20 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2fe30 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2fe40 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2fe50 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2fe60 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2fe70 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2fe80 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2fe90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2fea0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2feb0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2fec0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2fed0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2fee0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2fef0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2ff00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ff10 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2ff20 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2ff30 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2ff40 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2ff50 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2ff60 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2ff70 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2ff80 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2ff90 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2ffa0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2ffb0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2ffc0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2ffd0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2ffe0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2fff0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
30000 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
30010 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30020 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
30030 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
30040 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
30050 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
30060 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
30070 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
30080 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
30090 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
300a0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
300b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
300c0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
300d0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
300e0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
300f0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
30100 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30110 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
30120 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
30130 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
30140 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
30150 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
30160 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
30170 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
30180 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
30190 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
301a0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
301b0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
301c0 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
301d0 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
301e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
301f0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
30200 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30210 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
30220 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
30230 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
30240 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
30250 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
30260 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
30270 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
30280 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
30290 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
302a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
302b0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
302c0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
302d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
302e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
302f0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
30300 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
30310 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
30320 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
30330 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
30340 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
30350 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
30360 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
30370 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
30380 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
30390 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
303a0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
303b0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
303c0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
303d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
303e0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
303f0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
30400 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
30410 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
30420 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
30430 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
30440 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
30450 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
30460 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
30470 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
30480 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
30490 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
304a0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
304b0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
304c0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
304d0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
304e0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
304f0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
30500 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
30510 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
30520 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
30530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
30540 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
30550 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
30560 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
30570 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
30580 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
30590 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
305a0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
305b0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
305c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
305d0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
305e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
305f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
30600 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
30610 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
30620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30630 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
30640 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65  e used as argume
30650 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nts.** to [sqlit
30660 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30670 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  )], [sqlite3_bin
30680 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a  d_value()], and.
30690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
306a0 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  e_dup()]..** The
306b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
306c0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
306d0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
306e0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
306f0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
30700 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30710 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
30720 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
30740 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
30750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
30760 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
30770 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
30780 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
30790 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
307a0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
307b0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
307c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
307d0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
307e0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
307f0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
30800 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
30810 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
30820 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
30830 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30840 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
30850 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30860 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
30870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
30880 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
30890 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
308a0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
308b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
308c0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
308d0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
308e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
308f0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
30900 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
30910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
30920 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
30930 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
30940 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
30950 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
30960 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
30970 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
30990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
309a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
309b0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
309c0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
309d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
309e0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
309f0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
30a00 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
30a10 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
30a20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
30a30 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
30a40 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
30a50 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
30a60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30a70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
30a80 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
30a90 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
30aa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
30ab0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
30ac0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
30ad0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
30ae0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
30af0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
30b00 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
30b10 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
30b20 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
30b30 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
30b40 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
30b50 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
30b60 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
30b70 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
30b80 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
30b90 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
30ba0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
30bb0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
30bc0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
30bd0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
30be0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
30bf0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
30c00 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
30c10 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
30c20 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
30c30 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
30c40 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
30c50 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
30c60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
30c70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
30c80 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
30c90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
30ca0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
30cb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
30cc0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
30cd0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
30ce0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
30cf0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
30d00 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
30d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30d20 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
30d30 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
30d40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
30d50 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
30d60 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
30d70 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
30d80 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
30d90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
30da0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
30db0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
30dc0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
30dd0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
30de0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
30df0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
30e00 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
30e10 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
30e20 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
30e30 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
30e40 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
30e50 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
30e60 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
30e70 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
30e80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30e90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30ea0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
30eb0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
30ec0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
30ed0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
30ee0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
30ef0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
30f00 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
30f10 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
30f20 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
30f30 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
30f40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
30f50 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
30f60 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
30f70 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
30f80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
30f90 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
30fa0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
30fb0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
30fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30fd0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
30fe0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
30ff0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
31000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31010 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
31020 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
31030 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
31040 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
31050 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
31060 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
31070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
31080 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
31090 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
310a0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
310b0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
310c0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
310d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
310e0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
310f0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
31100 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
31110 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
31120 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
31130 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
31140 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
31150 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
31160 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31170 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
31180 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
31190 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
311a0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
311b0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
311c0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
311d0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
311e0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
311f0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
31200 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
31210 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
31220 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31230 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
31240 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
31250 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
31260 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
31270 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
31280 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
31290 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
312a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
312b0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
312c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
312d0 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
312e0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
312f0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
31300 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
31310 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
31320 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
31330 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
31340 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
31350 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
31360 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
31370 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
31380 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
31390 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
313a0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
313b0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
313c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
313d0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
313e0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
313f0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
31400 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
31410 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
31420 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
31430 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
31440 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
31450 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
31460 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
31470 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
31480 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
31490 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
314a0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
314b0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
314c0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
314d0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
314e0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
314f0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
31500 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
31510 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
31520 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
31530 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
31540 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
31550 74 6f 20 74 68 65 20 62 69 6e 64 20 41 50 49 20  to the bind API 
31560 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 65 70 74  fails,.** except
31570 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31580 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64 20 69 66  is not called if
31590 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
315a0 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 0a 2a  eter is a NULL.*
315b0 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 74 68 65  * pointer or the
315c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
315d0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  r is negative..*
315e0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
315f0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
31600 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
31610 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
31620 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
31630 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
31640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
31650 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
31660 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
31670 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
31680 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
31690 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
316a0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
316b0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
316c0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
316d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
316e0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
316f0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
31700 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
31710 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
31720 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
31730 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
31740 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
31750 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
31760 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
31770 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
31780 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
31790 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
317a0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
317b0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
317c0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
317d0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
317e0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
317f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31800 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
31810 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
31820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31830 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
31840 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
31850 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
31860 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
31870 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
31880 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
31890 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
318a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
318b0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
318c0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
318d0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
318e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
318f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
31900 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
31910 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
31920 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
31930 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
31940 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
31950 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
31960 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
31970 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
31980 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
31990 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
319a0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
319b0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
319c0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
319d0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
319e0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
319f0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
31a00 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
31a10 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
31a20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
31a30 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
31a40 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
31a50 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
31a60 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
31a70 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
31a80 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
31a90 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
31aa0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
31ab0 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54  _pointer(S,I,P,T
31ac0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73  ,D) routine caus
31ad0 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61  es the I-th para
31ae0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65  meter in.** [pre
31af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31b00 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51   S to have an SQ
31b10 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c  L value of NULL,
31b20 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a   but to also be.
31b30 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
31b40 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50  th the pointer P
31b50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20   of type T.  ^D 
31b60 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
31b70 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61   pointer or.** a
31b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
31b90 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
31ba0 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65  n for P. ^SQLite
31bb0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
31bc0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44  .** destructor D
31bd0 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61   with a single a
31be0 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65  rgument of P whe
31bf0 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64  n it is finished
31c00 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68   using.** P.  Th
31c10 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68  e T parameter sh
31c20 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63  ould be a static
31c30 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61   string, prefera
31c40 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20  bly a string.** 
31c50 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c  literal. The sql
31c60 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
31c70 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70  r() routine is p
31c80 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  art of the.** [p
31c90 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69  ointer passing i
31ca0 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20  nterface] added 
31cb0 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e  for SQLite 3.20.
31cc0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  0..**.** ^If any
31cd0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
31ce0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
31cf0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
31d00 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
31d10 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
31d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31d30 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
31d40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
31d50 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
31d60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
31d70 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
31d80 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
31d90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31da0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
31db0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
31dc0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
31dd0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
31de0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
31df0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
31e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31e10 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
31e20 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
31e30 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
31e40 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
31e50 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
31e60 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
31e70 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
31e80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
31e90 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
31ea0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
31eb0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
31ec0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
31ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31ee0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
31ef0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
31f00 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
31f10 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
31f20 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
31f30 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
31f40 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
31f50 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
31f60 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
31f70 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
31f80 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
31f90 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
31fa0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
31fb0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
31fc0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
31fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
31fe0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
31ff0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
32000 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
32010 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
32020 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
32030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
32040 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
32050 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
32060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
32070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
32080 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
32090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
320a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
320b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
320c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
320d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
320e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
320f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
32100 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
32110 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
32120 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
32130 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32140 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
32150 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
32160 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
32170 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
32180 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
32190 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
321a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
321b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
321c0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
321d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
321e0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
321f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
32200 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32210 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
32220 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
32230 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
32240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
32250 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
32260 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
32270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
32280 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
32290 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
322a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
322b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
322c0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
322d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
322e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
322f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32300 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32310 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
32320 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
32330 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
32340 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
32350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32360 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
32370 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
32380 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
32390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
323a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
323b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
323c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
323d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
323e0 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74  inter(sqlite3_st
323f0 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c  mt*, int, void*,
32400 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69   const char*,voi
32410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
32420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
32430 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
32440 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
32450 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
32460 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
32470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32480 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
32490 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
324a0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
324b0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
324c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
324d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
324e0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
324f0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
32500 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
32510 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
32520 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
32530 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
32540 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
32550 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
32560 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
32570 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
32580 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
32590 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
325a0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
325b0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
325c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
325d0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
325e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
325f0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
32600 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
32610 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
32620 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
32630 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
32640 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
32650 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
32660 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
32670 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
32680 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
32690 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
326a0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
326b0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
326c0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
326d0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
326e0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
326f0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
32700 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
32710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32720 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
32730 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
32740 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
32750 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
32760 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
32770 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
32780 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
32790 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
327a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
327b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
327c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
327d0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
327e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
327f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
32800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
32810 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
32820 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32830 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
32840 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
32850 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
32860 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32870 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
32880 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
32890 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
328a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
328b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
328c0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
328d0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
328e0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
328f0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
32900 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
32910 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
32920 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
32930 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
32940 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
32950 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
32960 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
32970 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
32980 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
32990 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
329a0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
329b0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
329c0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
329d0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
329e0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
329f0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
32a00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
32a10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
32a20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
32a30 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
32a40 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
32a50 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
32a60 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
32a70 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
32a80 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
32a90 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
32aa0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
32ab0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
32ac0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
32ad0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
32ae0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
32af0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
32b00 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
32b10 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
32b20 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
32b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32b40 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
32b50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32b60 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
32b70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
32b80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
32b90 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
32ba0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
32bb0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
32bc0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
32bd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32be0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
32bf0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32c00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32c10 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
32c20 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
32c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
32c40 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
32c50 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
32c60 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
32c70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32c80 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
32c90 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
32ca0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
32cb0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
32cc0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
32cd0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
32ce0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
32cf0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
32d00 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
32d10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
32d20 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
32d30 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
32d40 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
32d50 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
32d60 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
32d70 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
32d80 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
32d90 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
32da0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
32db0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
32dc0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
32dd0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
32de0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32df0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
32e00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32e10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
32e20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
32e30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
32e40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
32e50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32e60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
32e70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
32e80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
32e90 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
32ea0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32eb0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
32ec0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
32ed0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
32ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
32ef0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
32f00 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
32f10 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
32f20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32f30 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
32f40 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
32f50 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
32f60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
32f70 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
32f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
32f90 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
32fa0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
32fb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
32fc0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
32fd0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
32fe0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
32ff0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
33000 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
33010 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
33020 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
33030 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
33040 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
33050 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
33060 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33070 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
33080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
33090 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
330a0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
330b0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
330c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
330d0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
330e0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
330f0 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
33100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33110 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
33120 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
33130 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
33140 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
33150 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
33160 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
33170 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
33180 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
33190 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
331a0 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
331b0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
331c0 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
331d0 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
331e0 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
331f0 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
33200 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
33210 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
33220 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
33230 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
33240 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
33250 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
33260 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
33270 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
33280 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33290 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
332a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
332b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
332c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
332d0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
332e0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
332f0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
33300 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33310 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
33320 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
33330 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
33340 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
33350 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
33360 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
33370 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
33380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33390 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
333a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
333b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
333c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
333d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
333e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
333f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
33400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
33410 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
33420 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
33430 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
33440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
33450 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33460 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
33470 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
33480 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
33490 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
334a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
334b0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
334c0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
334d0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
334e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
334f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
33500 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
33510 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
33520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33530 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
33540 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
33550 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
33560 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
33570 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
33580 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
33590 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
335a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
335b0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
335c0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
335d0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
335e0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
335f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
33600 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
33610 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
33620 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
33630 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
33640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
33650 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
33660 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
33670 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
33680 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
33690 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
336a0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
336b0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
336c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
336d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
336e0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
336f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
33700 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33710 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
33720 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
33730 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
33740 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
33750 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
33760 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
33770 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
33780 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
33790 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
337a0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
337b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
337c0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
337d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
337e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
337f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33800 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
33810 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
33820 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
33830 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
33840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33850 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
33860 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
33870 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
33880 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33890 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
338a0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
338b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
338c0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
338d0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
338e0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
338f0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
33900 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
33910 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
33920 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
33930 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
33940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
33950 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
33960 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
33970 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
33980 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
33990 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
339a0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
339b0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
339c0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
339d0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
339e0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
339f0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
33a00 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
33a10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
33a20 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
33a30 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
33a40 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
33a50 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
33a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33a70 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
33a80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
33a90 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
33aa0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
33ab0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
33ac0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
33ad0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
33ae0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33af0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
33b00 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
33b10 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
33b20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
33b30 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
33b40 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
33b50 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
33b60 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
33b70 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
33b80 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
33b90 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
33ba0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
33bb0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
33bc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
33bd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
33be0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
33bf0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33c00 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
33c10 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
33c20 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
33c30 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
33c40 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
33c50 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
33c60 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
33c70 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
33c80 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
33c90 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
33ca0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
33cb0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
33cc0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
33cd0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
33ce0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
33cf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
33d00 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
33d10 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
33d20 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
33d30 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
33d40 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
33d50 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
33d60 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
33d70 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
33d80 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
33d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
33da0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
33db0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
33dc0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
33dd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
33de0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
33df0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
33e00 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
33e10 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
33e20 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
33e30 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
33e40 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
33e50 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
33e60 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
33e70 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
33e80 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
33e90 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
33ea0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
33eb0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
33ec0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
33ed0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
33ee0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
33ef0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
33f00 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
33f10 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
33f20 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
33f30 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
33f40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
33f50 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
33f60 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
33f70 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
33f80 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
33f90 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
33fa0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
33fb0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
33fc0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
33fd0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
33fe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
33ff0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
34000 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
34010 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
34020 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
34030 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
34040 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
34050 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
34060 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
34070 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
34080 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
34090 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
340a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
340b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
340c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
340d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
340e0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
340f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
34100 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
34120 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
34130 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
34140 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
34150 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
34160 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
34170 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
34180 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34190 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
341a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
341b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
341c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
341d0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
341e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
341f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
34210 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
34220 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
34230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34240 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
34250 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
34260 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
34270 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
34280 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
34290 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
342a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
342b0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
342c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
342d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
342e0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
342f0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
34300 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
34310 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
34320 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
34330 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
34340 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
34350 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
34360 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
34370 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
34380 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
34390 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
343a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
343b0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
343c0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
343d0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
343e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
343f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
34400 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
34410 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
34420 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
34430 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
34440 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
34450 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
34460 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
34470 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
34480 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
34490 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
344a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
344b0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
344c0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
344d0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
344e0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
344f0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
34500 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
34510 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
34520 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
34530 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
34540 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
34550 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
34560 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
34570 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
34580 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
34590 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
345a0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
345b0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
345c0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
345d0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
345e0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
345f0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
34600 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
34610 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
34620 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
34630 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
34640 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
34650 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
34660 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
34670 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
34680 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
34690 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
346a0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
346b0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
346c0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
346d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
346e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
346f0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
34700 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
34710 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34720 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
34730 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
34740 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
34750 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
34760 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
34770 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
34780 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
34790 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
347a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
347b0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
347c0 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b  sing any of.** [
347d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
347e0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
347f0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
34800 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
34810 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  6_v2()],.** or [
34820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
34830 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v3()] or one o
34840 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
34850 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
34860 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
34870 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
34880 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
34890 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
348a0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
348b0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
348c0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
348d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
348e0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
348f0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
34900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
34910 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
34920 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
34930 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
34940 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
34950 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74  e newer "vX" int
34960 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69  erfaces.** [sqli
34970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
34980 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
34990 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
349a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
349b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
349c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
349d0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
349e0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
349f0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
34a00 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
34a10 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
34a20 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
34a30 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e  e.** new "vX" in
34a40 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
34a50 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
34a60 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
34a70 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
34a80 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
34a90 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
34aa0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
34ab0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
34ac0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
34ad0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
34ae0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
34af0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
34b00 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
34b10 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
34b20 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
34b30 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
34b40 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
34b50 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
34b60 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
34b70 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
34b80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
34b90 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
34ba0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
34bb0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
34bc0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
34bd0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
34be0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
34bf0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
34c00 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
34c10 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
34c20 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
34c30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
34c40 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
34c50 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
34c60 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
34c70 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
34c80 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
34c90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
34ca0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
34cb0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
34cc0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
34cd0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
34ce0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
34cf0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
34d00 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
34d10 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
34d20 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
34d30 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
34d40 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
34d50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
34d60 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
34d70 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
34d80 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
34d90 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
34da0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
34db0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
34dc0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
34dd0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
34de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34df0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
34e00 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
34e10 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
34e20 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
34e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
34e40 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
34e50 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
34e60 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
34e70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
34e80 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
34e90 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
34ea0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
34eb0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
34ec0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
34ed0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
34ee0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
34ef0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
34f00 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
34f10 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
34f20 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
34f30 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
34f40 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
34f50 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
34f60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
34f70 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
34f80 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
34f90 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
34fa0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
34fb0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
34fc0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
34fd0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
34fe0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
34ff0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
35000 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
35010 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
35020 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
35030 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
35040 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
35050 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
35060 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
35070 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
35080 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
35090 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
350a0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
350b0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
350c0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
350d0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
350e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
350f0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
35100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
35110 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
35120 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
35130 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
35140 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
35150 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
35160 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
35170 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
35180 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
35190 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
351a0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
351b0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
351c0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
351d0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
351e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
351f0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
35200 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
35210 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
35220 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
35230 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
35240 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
35250 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
35260 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
35270 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
35280 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
35290 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
352a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
352b0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
352c0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
352d0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
352e0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
352f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
35300 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
35310 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
35320 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
35330 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
35340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
35350 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
35360 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
35370 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
35380 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
35390 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
353a0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
353b0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
353c0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
353d0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
353e0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
353f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35400 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
35410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
35420 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
35430 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
35440 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
35450 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
35460 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65  .  But after [ve
35470 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20  rsion 3.6.23.1] 
35480 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e  ([dateof:3.6.23.
35490 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  1],.** sqlite3_s
354a0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
354b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
354c0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
354d0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
354e0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
354f0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
35500 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
35510 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
35520 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
35530 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
35540 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
35550 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
35560 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
35570 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
35580 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
35590 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
355a0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
355b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
355c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
355d0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
355e0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
355f0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
35600 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
35610 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
35620 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
35630 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
35640 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
35650 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
35660 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
35670 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
35680 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
35690 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
356a0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
356b0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
356c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
356d0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
356e0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
356f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
35700 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35710 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
35720 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
35730 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
35740 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
35750 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
35760 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
35770 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
35780 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
35790 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
357a0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
357b0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
357c0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
357d0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
357e0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
357f0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ents.** using [s
35800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
35810 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  3()] or [sqlite3
35820 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
35830 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
35840 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
35850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35860 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61  e16_v3()] instea
35870 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
35880 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
35890 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
358a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
358b0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
358c0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
358d0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
358e0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
358f0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
35900 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
35910 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
35920 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
35930 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
35940 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35950 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
35960 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35970 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
35980 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
35990 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
359a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
359b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
359c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
359d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
359e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
359f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
35a00 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
35a10 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
35a20 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
35a30 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
35a40 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
35a50 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
35a60 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
35a70 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
35a80 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
35a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
35aa0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
35ab0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
35ac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
35ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
35ae0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
35af0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
35b00 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
35b10 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
35b20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
35b30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35b40 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35b50 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
35b60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35b70 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
35b80 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
35b90 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
35ba0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
35bb0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
35bc0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
35bd0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
35be0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
35bf0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
35c00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
35c10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
35c20 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
35c30 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
35c40 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
35c50 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
35c60 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
35c70 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
35c80 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
35c90 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
35ca0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
35cb0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
35cc0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
35cd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
35ce0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
35cf0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
35d00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
35d10 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
35d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35d30 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
35d40 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
35d50 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
35d60 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
35d70 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
35d80 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
35d90 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
35da0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
35db0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
35dc0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
35dd0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
35de0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
35df0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
35e00 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
35e10 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
35e20 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
35e30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
35e40 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
35e50 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
35e60 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
35e70 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
35e80 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
35e90 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
35ea0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
35eb0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
35ec0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
35ed0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
35ee0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
35ef0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
35f00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
35f10 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
35f20 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
35f30 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
35f40 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
35f50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
35f60 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
35f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
35f80 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
35f90 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
35fa0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
35fb0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
35fc0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
35fd0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
35fe0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
35ff0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
36000 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
36010 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
36020 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
36030 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
36040 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
36050 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
36060 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
36070 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
36080 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
36090 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72  .**.** <b>Summar
360a0 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b  y:</b>.** <block
360b0 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72  quote><table bor
360c0 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e  der=0 cellpaddin
360d0 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d  g=0 cellspacing=
360e0 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  0>.** <tr><td><b
360f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36100 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  blob</b><td>&rar
36110 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c  r;<td>BLOB resul
36120 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
36130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
36140 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  ouble</b><td>&ra
36150 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75  rr;<td>REAL resu
36160 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
36170 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36180 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  int</b><td>&rarr
36190 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45  ;<td>32-bit INTE
361a0 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
361b0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
361c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62  _column_int64</b
361d0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36  ><td>&rarr;<td>6
361e0 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  4-bit INTEGER re
361f0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
36200 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36210 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72  n_text</b><td>&r
36220 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45  arr;<td>UTF-8 TE
36230 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
36240 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36250 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62  column_text16</b
36260 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
36270 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c  TF-16 TEXT resul
36280 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
36290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
362a0 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  alue</b><td>&rar
362b0 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74  r;<td>The result
362c0 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69   as an .** [sqli
362d0 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74  te3_value|unprot
362e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
362f0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  lue] object..** 
36300 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  <tr><td>&nbsp;<t
36310 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
36320 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  p;.** <tr><td><b
36330 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36340 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61  bytes</b><td>&ra
36350 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61  rr;<td>Size of a
36360 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54   BLOB.** or a UT
36370 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20  F-8 TEXT result 
36380 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
36390 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
363a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62  olumn_bytes16&nb
363b0 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a  sp;&nbsp;</b>.**
363c0 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70   <td>&rarr;&nbsp
363d0 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20  ;&nbsp;<td>Size 
363e0 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58  of UTF-16.** TEX
363f0 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  T in bytes.** <t
36400 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36410 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e  _column_type</b>
36420 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65  <td>&rarr;<td>De
36430 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70  fault.** datatyp
36440 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a  e of the result.
36450 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f  ** </table></blo
36460 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c  ckquote>.**.** <
36470 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a  b>Details:</b>.*
36480 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
36490 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
364a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
364b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
364c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
364d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
364e0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
364f0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
36500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
36510 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
36520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36530 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
36540 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
36550 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
36560 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
36570 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
36580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
36590 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
365a0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
365b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
365c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
365d0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
365e0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
365f0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
36600 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
36610 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
36620 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
36630 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
36640 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
36650 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
36660 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
36670 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
36680 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
36690 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
366a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
366b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
366c0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
366d0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
366e0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
366f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
36700 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
36710 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
36720 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
36730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
36740 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
36750 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
36760 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
36770 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
36780 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
36790 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
367a0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
367b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
367c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
367d0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
367e0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
367f0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
36800 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
36810 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
36820 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
36830 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
36840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
36850 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
36860 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
36870 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
36880 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
36890 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
368a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
368b0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
368c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
368d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
368e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
368f0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
36900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
36910 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
36920 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
36930 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
36940 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
36950 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
36960 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
36970 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78  ** The first six
36980 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c   interfaces (_bl
36990 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e  ob, _double, _in
369a0 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74  t, _int64, _text
369b0 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a  , and _text16).*
369c0 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68  * each return th
369d0 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73  e value of a res
369e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20  ult column in a 
369f0 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f  specific data fo
36a00 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65  rmat.  If.** the
36a10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
36a20 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20  s not initially 
36a30 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64  in the requested
36a40 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61   format (for exa
36a50 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20  mple,.** if the 
36a60 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e  query returns an
36a70 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65   integer but the
36a80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36a90 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65  text() interface
36aa0 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65  .** is used to e
36ab0 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65  xtract the value
36ac0 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61  ) then an automa
36ad0 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
36ae0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
36af0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
36b10 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
36b20 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
36b30 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
36b40 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
36b50 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
36b60 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
36b70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
36b80 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
36b90 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
36ba0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
36bb0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
36bc0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
36bd0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
36be0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
36bf0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20  ..** The return 
36c00 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33  value of sqlite3
36c10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63  _column_type() c
36c20 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
36c30 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66  cide which.** of
36c40 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69   the first six i
36c50 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
36c60 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  be used to extra
36c70 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61  ct the column va
36c80 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  lue..** The valu
36c90 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
36ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36cb0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
36cc0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20  ingful if no.** 
36cd0 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
36ce0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
36cf0 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65  occurred for the
36d00 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69   value in questi
36d10 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61  on.  .** After a
36d20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36d30 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
36d40 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
36d50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
36d60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74   is undefined, t
36d70 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20  hough harmless. 
36d80 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
36d90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
36da0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
36db0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
36dc0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
36dd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
36de0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
36df0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
36e00 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
36e10 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74  a TEXT string, t
36e20 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
36e30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
36e40 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
36e50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e  umn_bytes16() in
36e60 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20  terfaces can be 
36e70 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e  used to determin
36e80 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66  e the size.** of
36e90 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
36ea0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
36eb0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
36ec0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
36ed0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
36ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36ef0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
36f00 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
36f10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
36f20 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
36f30 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
36f40 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
36f50 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
36f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36f70 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
36f80 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
36f90 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
36fa0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
36fb0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
36fc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
36fd0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
36fe0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
36ff0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
37000 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
37010 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
37020 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
37030 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
37040 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
37050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
37060 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
37070 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
37080 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
37090 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
370a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
370b0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
370c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
370d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
370e0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
370f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
37100 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
37110 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
37120 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37130 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
37140 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
37150 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
37160 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
37170 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
37180 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
37190 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
371a0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
371b0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
371c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
371d0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
371e0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
371f0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
37200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37210 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
37220 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
37230 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
37240 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
37250 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
37260 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
37270 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
37280 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
37290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
372a0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
372b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
372c0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
372d0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
372e0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
372f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
37300 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
37310 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
37320 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
37330 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
37340 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
37350 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
37360 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
37370 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
37380 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
37390 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
373a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
373b0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
373c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
373d0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
373e0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
373f0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
37400 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
37410 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
37420 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
37430 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
37440 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
37450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37460 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
37470 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
37480 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
37490 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
374a0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
374b0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
374c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
374d0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
374e0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
374f0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
37500 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
37510 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
37520 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
37530 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
37540 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
37550 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37560 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
37570 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
37580 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
37590 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
375a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
375b0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
375c0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
375d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
375e0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
375f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37600 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
37610 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
37620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
37630 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
37640 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
37650 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
37660 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
37670 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
37680 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
37690 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
376a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
376b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
376c0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
376d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
376e0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
376f0 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
37700 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e  readsafe..** Hen
37710 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
37720 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69  column_value() i
37730 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e  nterface.** is n
37740 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65  ormally only use
37750 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69  ful within the i
37760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
37770 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f   .** [applicatio
37780 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37790 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72  nctions] or [vir
377a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f  tual tables], no
377b0 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d  t within.** top-
377c0 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f  level applicatio
377d0 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n code..**.** Th
377e0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
377f0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
37800 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61  convert the data
37810 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
37820 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d  lt..** ^For exam
37830 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
37840 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
37850 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
37860 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
37870 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
37880 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
37890 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
378a0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
378b0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
378c0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
378d0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
378e0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
378f0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
37900 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
37910 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
37920 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
37930 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
37940 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
37950 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
37960 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
37970 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
37980 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
37990 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
379a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
379b0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
379c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
379d0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
379e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
379f0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
37a00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
37a10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
37a20 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
37a30 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
37a40 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
37a50 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
37a60 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
37a70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
37a80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
37a90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
37aa0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
37ab0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
37ac0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
37ad0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
37ae0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
37af0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
37b00 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
37b10 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
37b20 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
37b30 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
37b40 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
37b50 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
37b60 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
37b70 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
37b80 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
37b90 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
37ba0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
37bb0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
37bc0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
37bd0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
37be0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
37bf0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
37c00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
37c10 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
37c20 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
37c30 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
37c40 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
37c50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
37c60 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
37c70 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
37c80 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
37c90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
37ca0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
37cb0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
37cc0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
37cd0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
37ce0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
37cf0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
37d00 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
37d10 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
37d20 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
37d30 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
37d40 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
37d50 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
37d60 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
37d70 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
37d80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
37d90 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
37da0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
37db0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
37dc0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
37dd0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
37de0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
37df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37e00 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
37e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37e20 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
37e30 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
37e40 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
37e50 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
37e60 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
37e70 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
37e80 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
37e90 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
37ea0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
37eb0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
37ec0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
37ed0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
37ee0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
37ef0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
37f00 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
37f10 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
37f20 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
37f30 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
37f40 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
37f50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
37f60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
37f70 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
37f80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37f90 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
37fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37fb0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
37fc0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
37fd0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
37fe0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
37ff0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
38000 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
38010 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
38020 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
38030 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
38040 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
38050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
38060 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
38070 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
38080 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
38090 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
380a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
380b0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
380c0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
380d0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
380e0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
380f0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
38100 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
38110 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
38120 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
38130 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
38140 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
38150 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
38160 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
38170 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
38180 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
38190 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
381a0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
381b0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
381c0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
381d0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
381e0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
381f0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
38200 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
38210 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
38220 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
38230 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
38240 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
38250 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
38260 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
38270 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
38280 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
38290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
382a0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
382b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
382c0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
382d0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
382e0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
382f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
38300 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
38310 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
38320 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
38330 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
38340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
38350 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
38360 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
38370 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
38380 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
38390 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
383a0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
383b0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
383c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
383d0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
383e0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
383f0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
38400 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
38410 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
38420 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
38430 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
38440 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
38450 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
38460 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
38470 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
38480 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
38490 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
384a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
384b0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
384c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
384d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
384e0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
384f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
38500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
38510 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
38520 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
38530 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
38540 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
38550 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
38560 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
38570 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
38580 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
38590 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
385a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
385b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
385c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
385d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
385e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
385f0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
38600 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
38610 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
38620 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
38630 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74  tically.  Do not
38640 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
38650 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
38660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
38670 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
38680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
38690 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
386a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
386b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ()]..**.** As lo
386c0 6e 67 20 61 73 20 74 68 65 20 69 6e 70 75 74 20  ng as the input 
386d0 70 61 72 61 6d 65 74 65 72