/ Hex Artifact Content
Login

Artifact a8ac449be3b5f7edeaf9066bec560323a61fcd032f199f7f462444afda119151:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6910: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6930: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6940: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6950: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6960: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6970: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6980: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6990: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
69a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
69b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
69c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
69d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
69e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
69f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6a00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6a20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6a30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6a60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6a70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6a80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6aa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6ab0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6ac0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6ad0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6ae0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6af0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6b00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6b10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6b20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6b30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6b60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6b70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6b80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ba0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6bb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6bc0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6bd0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6be0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6bf0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6c00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6c20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6c30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6c40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6c50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6c60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6c70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6c80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6ca0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6cb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6cc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6cd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6ce0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6cf0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6d00: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6d10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6d20: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6d30: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6d40: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6d50: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6d60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6d70: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6d80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d90: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6dd0: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6de0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6df0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6e00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6e10: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6e20: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6e30: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6e40: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6e50: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6e60: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6e70: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6e80: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e90: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6eb0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6ec0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6ed0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6ee0: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6ef0: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6f00: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6f10: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6f20: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6f30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6f40: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6f50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6f60: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6f70: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6f80: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f90: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6fa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6fb0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6fc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6fd0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ff0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
7000: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
7030: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7040: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7070: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7090: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
70a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
70b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
70c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
70d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
70e0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
70f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7100: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7110: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7130: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7140: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7150: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7180: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
71a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
71b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
71c0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
71d0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
71e0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
71f0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7210: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7220: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7240: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7250: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7260: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
7270: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
7280: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
72c0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
72d0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
72e0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
72f0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7300: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7310: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7320: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7330: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7340: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7350: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7360: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7370: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
7380: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7390: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
73a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
73c0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
73d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
73e0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7400: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7420: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7430: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7440: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7450: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7460: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
7470: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
7480: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7490: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
74a0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
74b0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
74c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
74d0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
74e0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
74f0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7500: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7520: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7550: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7560: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
7570: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
7580: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7590: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
75a0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
75b0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
75c0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
75d0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
75e0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
75f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7610: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7620: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7630: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7640: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7650: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7660: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
7670: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
7680: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7690: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
76a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
76b0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
76c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
76d0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
76e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
76f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7700: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7710: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7720: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7730: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7740: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7750: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7760: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7770: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7780: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7790: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
77a0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
77b0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
77c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
77d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
77e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
77f0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7800: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7810: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7820: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7830: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7840: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7850: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7860: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7870: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7880: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7890: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
78a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
78b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
78c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
78d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
78e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
78f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7900: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7910: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7920: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7930: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7940: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7950: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7960: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7980: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7990: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
79a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
79b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
79c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
79d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
79f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7a00: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7a10: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7a50: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7a70: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7a80: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a90: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7ab0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7ac0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7ad0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7ae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7af0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7b00: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7b10: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7b20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7b30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7b40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7b50: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7b60: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7b70: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7b80: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b90: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7bb0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7bc0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7bd0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7be0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7c00: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7c10: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7c20: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7c30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7c40: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7c50: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7c60: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7c70: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c90: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7ca0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7cd0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7ce0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7d00: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7d10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7d20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7d30: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7d40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7d50: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7d60: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7d70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7d80: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d90: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7da0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7db0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7dc0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7de0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7df0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e00: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7e10: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7e20: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7e30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7e40: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7e50: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7e60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7e70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e80: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e90: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7ea0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7eb0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7ec0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7ed0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7ee0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7ef0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7f00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7f10: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7f20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7f30: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7f40: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f60: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7f70: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7f80: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f90: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7fa0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7fb0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7fc0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7fd0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7fe0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7ff0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
8000: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
8010: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
8020: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
8030: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
8040: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
8050: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
8060: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
8070: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
8080: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8090: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
80a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
80b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
80c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
80d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8100: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8120: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8130: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8140: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8150: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8160: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
8170: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
8180: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8190: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
81a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
81b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
81c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
81d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
81e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
81f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8200: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8210: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8220: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8230: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8240: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8250: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8260: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
8270: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
8280: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8290: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
82a0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
82c0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
82d0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
82e0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
82f0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8310: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8320: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8330: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8340: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8350: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8360: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
8370: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
8380: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8390: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
83a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
83b0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
83c0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
83d0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
83e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
83f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8400: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8410: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8420: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8430: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8440: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8450: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8460: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
8470: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
8480: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8490: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
84a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
84b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
84c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
84d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
84e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
84f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8500: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8510: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8520: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8530: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8540: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8550: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8560: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
8570: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
8580: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8590: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
85a0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
85b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
85c0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
85d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
85e0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
85f0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8600: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8610: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8630: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8640: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8650: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8660: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
8670: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
8680: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8690: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
86a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
86b0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
86c0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
86d0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
86e0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
86f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8700: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8710: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8720: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8730: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8740: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8750: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8760: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8770: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
8780: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8790: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
87a0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
87b0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
87c0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
87d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8810: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8830: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8890: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
88a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
88b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
88e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8910: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8920: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8930: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8960: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
8980: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8990: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
89a0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
89b0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
89c0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
89d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
89e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
89f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8a00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8a10: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8a20: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8a30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8a60: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8a70: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8a80: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a90: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8aa0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8ab0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8ac0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8ad0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8ae0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8b00: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8b10: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8b20: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b30: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8b40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b50: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8b60: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8b70: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8b80: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b90: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ba0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8bb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8bd0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8be0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8bf0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8c00: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8c10: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8c20: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8c30: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8c40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8c50: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8c60: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8c70: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8c80: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c90: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8ca0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8cb0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8cc0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8cd0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8ce0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8cf0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d00: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8d10: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8d20: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8d30: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8d50: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8d70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8d80: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d90: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8da0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8db0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8dc0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8dd0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8de0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8df0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8e00: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8e10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8e20: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8e30: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8e40: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8e50: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e70: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ea0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8eb0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(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 2a 70 53 69  lite3_int64 *pSi
8ee0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8ef0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8f00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8f10: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8f20: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8f30: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8f40: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8f50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8f60: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8f70: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f90: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8fa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8fb0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8fc0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8fd0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8fe0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8ff0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9000: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9010: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9020: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9030: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9040: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9050: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9060: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9070: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9080: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9090: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
90a0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
90b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
90c0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
90d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
90e0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9100: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9110: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9120: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9130: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9140: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9160: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9170: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9180: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9190: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
91a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
91b0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
91c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91e0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
91f0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9200: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9210: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9220: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9230: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9240: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9250: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9260: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
9270: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
9280: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9290: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
92a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
92b0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
92c0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
92d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
92e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
92f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9300: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9330: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9360: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9370: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9380: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9390: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
93a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
93b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
93c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
93d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
93e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
93f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9400: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9410: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9420: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9430: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9440: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9450: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9460: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9470: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
9480: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9490: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
94a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
94b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
94c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
94d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
94e0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
94f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9500: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9510: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9520: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9540: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9560: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
9570: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
9580: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9590: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
95a0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
95b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
95c0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
95d0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
95e0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
95f0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9600: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9610: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9620: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9630: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9640: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9650: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9660: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9670: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9680: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9690: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
96a0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
96b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
96c0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
96d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
96e0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
96f0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9710: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9720: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9730: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9740: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9750: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9760: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9770: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9780: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9790: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
97a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
97b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
97c0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
97d0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
97e0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
97f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9800: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9810: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9820: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9830: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9850: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9860: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9870: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9880: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9890: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
98a0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
98b0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
98c0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
98d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
98e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
98f0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9900: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9910: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9920: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9930: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9940: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9950: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9960: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9970: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9980: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9990: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
99a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
99b0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
99c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
99d0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
99e0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
99f0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9a00: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9a10: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9a20: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9a30: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9a40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9a50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
9a60: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
9a70: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
9a80: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
9a90: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
9aa0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
9ab0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9ac0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9ad0: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9ae0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9af0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9b20: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9b30: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9b40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9b50: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9b60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9b70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9b80: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9b90: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9ba0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9bb0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9bc0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9bd0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9be0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9bf0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9c00: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9c10: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9c20: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9c30: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9c40: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9c50: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9c60: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9c70: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9c80: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9c90: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9ca0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9cb0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9cc0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9cd0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9ce0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9cf0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9d00: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9d10: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9d20: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9d30: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9d40: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9d50: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9d60: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9d70: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9d80: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9d90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9da0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9db0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9dc0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9dd0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9de0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9df0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9e00: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9e10: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9e20: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9e30: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9e40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9e50: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9e60: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9e70: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9e80: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9e90: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9ea0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9eb0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9ec0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9ed0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9ee0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9ef0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9f00: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9f10: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9f20: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9f30: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9f40: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9f50: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9f60: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9f70: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9f80: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9f90: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9fa0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9fb0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9fc0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9fd0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9fe0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9ff0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
a000: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
a010: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a020: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
a030: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
a040: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
a050: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
a060: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
a070: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
a080: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
a090: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a0a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
a0b0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
a0c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a0d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a0e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0f0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a100: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a110: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a120: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a130: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a140: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a150: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a160: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a170: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a180: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a190: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a1a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a1b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a1c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a1d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a1e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a1f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a200: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a210: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a220: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a230: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a240: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a250: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a260: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a270: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a280: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a290: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a2a0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a2b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a2c0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a2d0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a2e0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a2f0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a300: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a310: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a320: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a330: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a340: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a350: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a360: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a370: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a380: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a390: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a3a0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a3b0: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a3c0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a3d0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a3e0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a3f0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a400: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a410: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a420: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a430: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a440: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a450: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a460: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a470: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a480: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a490: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a4a0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a4b0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a4c0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a4d0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a4e0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a500: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a520: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a530: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a540: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a550: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a560: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a570: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a580: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a590: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a5a0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 28 5b 57  te ahead log ([W
a5b0: 41 4c 20 66 69 6c 65 5d 29 20 61 6e 64 20 73 68  AL file]) and sh
a5c0: 61 72 65 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ared memory.** f
a5d0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a5e0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a5f0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a600: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a610: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a620: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a640: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a650: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a660: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a670: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a680: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a690: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a6a0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a6b0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a6c0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a6d0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a6e0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a6f0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a700: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a710: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a720: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a730: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a740: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a750: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a760: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a770: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a780: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a790: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a7a0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a7b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a7c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a7d0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a7e0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a7f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a800: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a810: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a820: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a830: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a840: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a850: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a860: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a870: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a880: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a890: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a8a0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a8b0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a8d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a8e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a8f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a910: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a920: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a930: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a940: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a950: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a960: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a970: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a980: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a990: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a9a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a9b0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a9c0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a9d0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a9e0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a9f0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
aa00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
aa10: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
aa20: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
aa30: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
aa40: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
aa50: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
aa60: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
aa70: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
aa80: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
aa90: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
aaa0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
aab0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
aac0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
aad0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aae0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aaf0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
ab10: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
ab20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab30: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
ab40: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
ab50: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
ab60: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
ab70: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
ab80: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
ab90: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aba0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
abb0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
abc0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
abd0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
abe0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
abf0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ac00: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ac10: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ac20: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ac30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ac40: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
ac50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ac60: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
ac70: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
ac80: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
ac90: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
aca0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
acb0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
acc0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
acd0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ace0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
acf0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ad00: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ad10: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ad20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ad30: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ad40: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ad50: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ad60: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
ad70: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
ad80: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
ad90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ada0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
adb0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
adc0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
add0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ade0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
adf0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ae00: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ae10: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ae20: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ae30: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ae40: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
ae50: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
ae60: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
ae70: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ae80: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
ae90: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
aea0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
aeb0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
aec0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
aed0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
aee0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
aef0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
af00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
af10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
af20: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
af30: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af40: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
af50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
af60: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
af70: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
af80: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
af90: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
afa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
afb0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
afc0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
afd0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
afe0: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
aff0: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
b000: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
b010: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
b020: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
b030: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
b040: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
b050: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
b060: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
b070: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
b080: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
b090: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
b0a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b0b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b0c0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
b0d0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b0e0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b0f0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b100: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b110: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b120: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b130: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b140: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b150: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b160: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b170: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b180: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b190: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b1a0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b1b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b1c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b1d0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b1e0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b1f0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b200: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b210: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b220: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b230: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b240: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b250: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b260: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b270: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b280: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b290: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b2a0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b2b0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b2c0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b2d0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b2e0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b2f0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b300: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b310: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b320: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b330: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b340: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b350: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b360: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b370: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b380: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b390: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b3a0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b3b0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b3c0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b3f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b400: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b410: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b420: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b430: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b440: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b450: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b460: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b470: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b480: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b490: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b4a0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b4b0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b4c0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b4d0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b4e0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b4f0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b500: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b510: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b520: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b530: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b540: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b550: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b560: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b570: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b580: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b590: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b5a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b5b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b5c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b5d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b5e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b5f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b600: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b610: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b620: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b630: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b640: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b650: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b660: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b670: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b680: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b690: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b6a0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b6b0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b6c0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b6d0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b6e0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b6f0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b710: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b720: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b730: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b740: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b750: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b760: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b780: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b790: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b7a0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b7b0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b7c0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b7d0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b7e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b7f0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b800: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b810: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b820: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b830: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b840: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b850: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b860: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b870: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b880: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b890: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b8a0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b8b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b8c0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b8d0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b8e0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b8f0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b900: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b910: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b920: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b930: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b940: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b950: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b960: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b970: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b980: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b990: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b9a0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b9b0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b9c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b9d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b9e0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b9f0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ba00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ba10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ba20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ba30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ba40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ba50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ba60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ba70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ba80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ba90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
baa0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
bab0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
bac0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
bad0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
bae0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
baf0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
bb00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
bb10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
bb20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
bb30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
bb40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
bb50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
bb60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
bb70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
bb80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
bb90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bba0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bbb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bbc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
bbd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bbf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bc00: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bc10: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bc20: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bc30: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bc40: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bc50: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bc60: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bc70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bc80: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bc90: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bca0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bcb0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bcc0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bcd0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bce0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bcf0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bd00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bd10: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bd20: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bd30: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bd40: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bd50: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bd60: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bd70: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bd80: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bd90: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bda0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bdb0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bdc0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bdd0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bde0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bdf0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
be00: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
be10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be20: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
be40: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
be50: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
be60: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
be70: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
be80: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
be90: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bea0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
beb0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bec0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bed0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
bee0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
bef0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
bf00: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bf10: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
bf20: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
bf30: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
bf40: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
bf50: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bf60: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bf70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bf80: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bf90: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bfa0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bfb0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bfc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bfd0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bfe0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bff0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
c000: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
c010: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
c020: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
c030: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
c040: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
c050: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
c060: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
c070: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
c080: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
c090: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
c0a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
c0b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
c0c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
c0d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c0e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c0f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c100: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c110: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c120: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c130: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c140: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c150: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c160: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c170: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c180: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c190: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c1a0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c1b0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c1d0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c1e0: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c1f0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c200: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c210: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c220: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c230: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c240: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c250: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c260: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c270: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c280: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c290: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c2a0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c2b0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c2c0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c2d0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c2e0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c2f0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c300: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c310: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c320: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c330: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c340: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c350: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c380: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c390: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c3a0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c3b0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c3c0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c3d0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c3e0: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c3f0: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c400: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c410: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c420: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c430: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c440: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c450: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c460: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c470: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c480: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c490: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c4a0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c4b0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c4c0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c4d0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c4e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c4f0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c500: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c510: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c520: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c530: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c540: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c550: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c560: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c570: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c580: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c590: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c5a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c5b0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c5c0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c5d0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c5e0: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c5f0: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c600: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c610: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c620: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c630: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c640: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c660: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c670: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c690: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c6a0: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c6b0: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c6c0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c6d0: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c6e0: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c6f0: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c700: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c710: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c720: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c730: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c740: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c750: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c760: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c770: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c780: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c790: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c7a0: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c7b0: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c7c0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c7d0: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c7e0: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c7f0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c800: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c810: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c820: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c830: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c840: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c860: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c870: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c880: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c890: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c8a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c8b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c8c0: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c8d0: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c8e0: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c8f0: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c900: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c910: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c920: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c930: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c950: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c980: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c990: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c9a0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c9b0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c9c0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c9d0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c9f0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
ca00: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
ca10: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
ca20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ca30: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ca40: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
ca50: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
ca60: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
ca70: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
ca80: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
ca90: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
caa0: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
cab0: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
cac0: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
cad0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
cae0: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
caf0: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
cb00: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
cb10: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
cb20: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
cb30: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cb40: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
cb50: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
cb60: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
cb70: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cb80: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cb90: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cba0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cbb0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cbc0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cbd0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cbe0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cbf0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cc00: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cc10: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cc20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cc30: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cc40: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cc50: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cc60: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cc70: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cc80: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cc90: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
ccb0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
ccc0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
ccd0: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cce0: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
ccf0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cd00: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cd10: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cd20: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cd30: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cd40: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cd50: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cd60: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cd80: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
cd90: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cda0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cdb0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cdc0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cdd0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cde0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cdf0: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
ce00: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
ce10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
ce20: 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61  MEOUT] opcode ca
ce30: 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f  uses attempts to
ce40: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c   obtain.** a fil
ce50: 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65  e lock using the
ce60: 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f   xLock or xShmLo
ce70: 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  ck methods of th
ce80: 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a  e VFS to wait.**
ce90: 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c   for up to M mil
cea0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
ceb0: 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20   failing, where 
cec0: 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20  M is the single 
ced0: 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  .** unsigned int
cee0: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a  eger parameter..
cef0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
cf10: 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b  RSION]].** The [
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
cf30: 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f 64  A_VERSION] opcod
cf40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 74  e is used to det
cf50: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
cf60: 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  * a database fil
cf70: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
cf80: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
cf90: 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
cfa0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  ed integer..** T
cfb0: 68 65 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e  he "data version
cfc0: 22 20 66 6f 72 20 74 68 65 20 70 61 67 65 72 20  " for the pager 
cfd0: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
cfe0: 74 68 65 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  the pointer.  Th
cff0: 65 0a 2a 2a 20 22 64 61 74 61 20 76 65 72 73 69  e.** "data versi
d000: 6f 6e 22 20 63 68 61 6e 67 65 73 20 77 68 65 6e  on" changes when
d010: 65 76 65 72 20 61 6e 79 20 63 68 61 6e 67 65 20  ever any change 
d020: 6f 63 63 75 72 73 20 74 6f 20 74 68 65 20 63 6f  occurs to the co
d030: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64  rresponding.** d
d040: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 65 69  atabase file, ei
d050: 74 68 65 72 20 74 68 72 6f 75 67 68 20 53 51 4c  ther through SQL
d060: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
d070: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
d080: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  .** connection o
d090: 72 20 74 68 72 6f 75 67 68 20 74 72 61 6e 73 61  r through transa
d0a0: 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74 74 65 64  ctions committed
d0b0: 20 62 79 20 73 65 70 61 72 61 74 65 20 64 61 74   by separate dat
d0c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d0d0: 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79 20 69 6e  ions possibly in
d0e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
d0f0: 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  . The [sqlite3_t
d100: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
d110: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  ** interface can
d120: 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
d130: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
d140: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
d150: 6f 6e 20 68 61 73 20 63 68 61 6e 67 65 64 2c 0a  on has changed,.
d160: 2a 2a 20 62 75 74 20 74 68 61 74 20 69 6e 74 65  ** but that inte
d170: 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74  rface responds t
d180: 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20 54 45 4d  o changes on TEM
d190: 50 20 61 73 20 77 65 6c 6c 20 61 73 20 4d 41 49  P as well as MAI
d1a0: 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f  N and does.** no
d1b0: 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68  t provide a mech
d1c0: 61 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20  anism to detect 
d1d0: 63 68 61 6e 67 65 73 20 74 6f 20 4d 41 49 4e 20  changes to MAIN 
d1e0: 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20 74 68 65  only.  Also, the
d1f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
d200: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
d210: 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73  terface responds
d220: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 63 68 61   to internal cha
d230: 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a  nges only and.**
d240: 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 20 6d   omits changes m
d250: 61 64 65 20 62 79 20 6f 74 68 65 72 20 64 61 74  ade by other dat
d260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d270: 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50 52 41 47  s.  The.** [PRAG
d280: 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d  MA data_version]
d290: 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65   command provide
d2a0: 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20   a mechanism to 
d2b0: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d2c0: 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 61 74  o.** a single at
d2d0: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20  tached database 
d2e0: 74 68 61 74 20 6f 63 63 75 72 20 64 75 65 20 74  that occur due t
d2f0: 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  o other database
d300: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a   connections,.**
d310: 20 62 75 74 20 6f 6d 69 74 73 20 63 68 61 6e 67   but omits chang
d320: 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  es implemented b
d330: 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
d340: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e 20 77 68 69  onnection on whi
d350: 63 68 20 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  ch it is.** call
d360: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 20 63  ed.  This file c
d370: 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65 20 6f 6e  ontrol is the on
d380: 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20  ly mechanism to 
d390: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d3a0: 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e 20 65 69  hat.** happen ei
d3b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
d3c0: 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79 20 61 6e  or externally an
d3d0: 64 20 74 68 61 74 20 61 72 65 20 61 73 73 6f 63  d that are assoc
d3e0: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 61 20  iated with.** a 
d3f0: 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 61 63  particular attac
d400: 68 65 64 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  hed database..**
d410: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
d420: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d430: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
d440: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
d450: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
d460: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d470: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
d490: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d4a0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
d4b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
d4c0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d4d0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
d4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d4f0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
d500: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
d510: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
d520: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d530: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
d540: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
d550: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
d560: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
d570: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d580: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
d590: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d5a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d5b0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
d5c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d5d0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
d5e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
d5f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d600: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
d610: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
d620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d630: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d640: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d660: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d670: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d690: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d6a0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d6c0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d6d0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d6e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d6f0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d700: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d710: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d720: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d730: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d740: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d750: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d760: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d780: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d790: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d7b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d7c0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d7e0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d7f0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d800: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d810: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d820: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d830: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d840: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d850: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d860: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d880: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d890: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d8b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d8c0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d8d0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d8e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d8f0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d900: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d920: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d930: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d950: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d960: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d980: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d990: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d9a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d9b0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d9c0: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d9d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d9e0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d9f0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
da00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
da10: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
da20: 20 20 20 20 20 20 33 34 0a 23 64 65 66 69 6e 65        34.#define
da30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41   SQLITE_FCNTL_DA
da40: 54 41 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TA_VERSION      
da50: 20 20 20 20 20 33 35 0a 0a 2f 2a 20 64 65 70 72       35../* depr
da60: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
da80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
da90: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
daa0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
dab0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
dac0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
dad0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
dae0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
daf0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
db00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
db10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
db20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
db30: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
db40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
db50: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
db60: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
db70: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
db80: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
db90: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
dba0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
dbb0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
dbc0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
dbd0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
dbe0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
dbf0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
dc00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
dc10: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
dc20: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dc30: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
dc40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
dc50: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
dc60: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
dc70: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
dc80: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
dc90: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
dca0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
dcb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
dcc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dcd0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
dce0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
dcf0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
dd00: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
dd10: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
dd20: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
dd30: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
dd40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
dd50: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
dd60: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
dd70: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
dd80: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
dd90: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
dda0: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ddb0: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ddc0: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ddd0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
dde0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ddf0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
de00: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
de10: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
de20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
de30: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
de40: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
de50: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
de60: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
de70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
de80: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
de90: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
dea0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
deb0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
dec0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
ded0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
dee0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
def0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
df00: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
df10: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
df20: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
df30: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
df40: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
df50: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
df60: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
df70: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
df80: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
df90: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
dfa0: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
dfb0: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
dfc0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
dfd0: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
dfe0: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
dff0: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
e000: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
e010: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e020: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
e030: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
e040: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
e050: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
e060: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
e070: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
e080: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
e090: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
e0a0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e0b0: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
e0c0: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
e0d0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
e0e0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e0f0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
e100: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
e110: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
e120: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
e130: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
e140: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
e150: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
e160: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
e170: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
e180: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
e190: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
e1a0: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
e1b0: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
e1c0: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
e1d0: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
e1e0: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
e1f0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e200: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e210: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
e220: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
e230: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
e240: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
e250: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
e260: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
e270: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
e280: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
e290: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
e2a0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
e2b0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
e2c0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
e2d0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
e2e0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
e2f0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
e300: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
e310: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
e320: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
e330: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
e340: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
e350: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
e360: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
e370: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
e380: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
e390: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
e3a0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
e3b0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
e3c0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
e3d0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
e3e0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
e3f0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
e400: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
e410: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
e420: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
e430: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
e440: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
e450: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
e460: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
e470: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
e480: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
e490: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
e4a0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
e4b0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
e4c0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
e4d0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
e4e0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
e4f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e500: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
e510: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
e520: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
e530: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
e540: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
e550: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
e560: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
e570: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
e580: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
e590: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
e5a0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
e5b0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
e5c0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
e5d0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
e5e0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
e5f0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
e600: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
e610: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e620: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
e630: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
e640: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
e650: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
e660: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
e670: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
e680: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
e690: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
e6a0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
e6b0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
e6c0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
e6d0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
e6e0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
e6f0: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
e700: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
e710: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
e720: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
e730: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
e740: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e750: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
e760: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
e770: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
e780: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
e790: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
e7a0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e7b0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
e7c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
e7d0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
e7e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
e7f0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
e800: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
e810: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
e820: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e830: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e840: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e850: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e860: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e870: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e880: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e890: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e8a0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e8b0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e8c0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e8d0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e8e0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e8f0: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e900: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e910: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e920: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e930: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e940: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e950: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e960: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e970: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e980: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e990: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e9a0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e9b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e9c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e9d0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e9e0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e9f0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
ea00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ea10: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
ea20: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
ea30: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
ea40: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
ea50: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
ea60: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
ea70: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
ea80: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ea90: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
eaa0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
eab0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
eac0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ead0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
eae0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
eaf0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
eb00: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
eb10: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
eb20: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
eb30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
eb40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eb50: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
eb60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
eb70: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
eb80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eb90: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
eba0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ebb0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
ebc0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ebd0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
ebe0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ebf0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
ec00: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ec10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
ec20: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
ec30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ec40: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
ec50: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
ec60: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
ec70: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
ec80: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
ec90: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
eca0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
ecb0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
ecc0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
ecd0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
ece0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
ecf0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
ed00: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
ed10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
ed20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
ed30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
ed40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
ed50: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
ed60: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
ed70: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
ed80: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
ed90: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
eda0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
edb0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
edc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
edd0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
ede0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
edf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
ee00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
ee10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
ee20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
ee30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
ee40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
ee50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
ee60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
ee70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
ee80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
ee90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
eea0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
eeb0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
eec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
eed0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
eee0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
eef0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ef00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
ef20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
ef30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
ef40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
ef50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
ef60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
ef70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ef80: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
ef90: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
efa0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
efb0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
efc0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
efd0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
efe0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
eff0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
f000: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
f010: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
f020: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
f030: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
f040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f050: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
f060: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
f070: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
f080: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
f090: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
f0a0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
f0b0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
f0c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f0d0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
f0e0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
f0f0: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
f100: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
f110: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
f120: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
f130: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
f140: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
f150: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
f160: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
f170: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
f180: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
f190: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
f1a0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
f1b0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
f1c0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
f1d0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
f1e0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
f1f0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
f200: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
f210: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
f220: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
f230: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
f240: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
f250: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
f260: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
f270: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
f280: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
f290: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
f2a0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
f2b0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
f2c0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
f2d0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
f2e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
f2f0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
f300: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
f310: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
f320: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
f330: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
f340: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
f350: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
f360: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
f370: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
f380: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
f390: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
f3a0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
f3b0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
f3c0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
f3d0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
f3e0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
f3f0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
f400: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
f410: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
f420: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
f430: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
f440: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
f450: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
f460: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
f470: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
f480: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
f490: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f4a0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
f4b0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
f4c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f4d0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
f4e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
f4f0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
f500: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
f510: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
f520: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
f530: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
f540: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
f550: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
f560: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
f570: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
f580: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
f590: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
f5a0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
f5b0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
f5c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
f5d0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
f5e0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
f5f0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
f600: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
f610: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
f620: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
f630: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
f640: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
f650: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
f660: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
f670: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
f680: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
f690: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
f6a0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
f6b0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
f6c0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
f6d0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
f6e0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
f6f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
f700: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
f710: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
f720: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
f730: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
f740: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f750: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
f760: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
f770: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
f780: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
f790: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
f7a0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
f7b0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
f7c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
f7d0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
f7e0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
f7f0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
f800: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
f810: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
f820: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f830: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f840: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f850: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f860: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f870: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f880: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f890: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f8a0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f8b0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f8c0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f8d0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f8e0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f8f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f900: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f910: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f920: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f930: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f940: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f950: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f960: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f970: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f980: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f990: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f9a0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f9b0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f9c0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f9d0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f9e0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f9f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
fa00: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
fa10: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
fa20: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
fa30: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
fa40: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
fa50: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
fa60: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
fa70: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
fa80: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
fa90: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
faa0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
fab0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
fac0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
fad0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fae0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
faf0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
fb00: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
fb10: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
fb20: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
fb30: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
fb40: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
fb50: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
fb60: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
fb70: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
fb80: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
fb90: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
fba0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
fbb0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
fbc0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
fbd0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
fbe0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
fbf0: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
fc00: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
fc10: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
fc20: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
fc30: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
fc40: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
fc50: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
fc60: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
fc70: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
fc80: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
fc90: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
fca0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
fcb0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
fcc0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
fcd0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
fce0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
fcf0: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
fd00: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
fd10: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
fd20: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
fd30: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
fd40: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
fd50: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
fd60: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
fd70: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
fd80: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
fd90: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
fda0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
fdb0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
fdc0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
fdd0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
fde0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
fdf0: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
fe00: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
fe10: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
fe20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
fe30: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
fe40: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
fe50: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
fe60: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
fe70: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
fe80: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
fe90: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
fea0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
feb0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
fec0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
fed0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
fee0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
fef0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
ff00: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
ff10: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
ff20: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
ff30: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
ff40: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
ff50: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
ff60: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ff70: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ff80: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ff90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ffa0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ffb0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ffc0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ffd0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ffe0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
fff0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
10000 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
10010 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
10020 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10030 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10040 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
10050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
10060 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
10070 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
10080 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
10090 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100a0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100b0 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
100c0 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
100d0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100f0 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
10100 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
10110 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
10120 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10130 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
10140 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
10150 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
10160 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
10170 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10180 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
10190 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
101a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
101b0 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
101c0 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
101d0 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
101e0 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
101f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
10200 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
10210 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
10220 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10230 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
10240 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
10250 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
10260 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
10270 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
10280 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
10290 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
102a0 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
102b0 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
102c0 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
102d0 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
102e0 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
102f0 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
10300 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
10310 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
10320 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
10330 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
10340 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
10350 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
10360 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
10370 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
10380 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
10390 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
103a0 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
103b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
103c0 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
103d0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
103e0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
103f0 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
10400 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
10410 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
10420 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
10430 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
10440 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
10450 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
10460 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10470 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10480 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
10490 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
104a0 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
104b0 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
104c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
104d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
104e0 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
104f0 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
10500 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10510 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10520 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
10530 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10540 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10550 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
10560 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
10570 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10580 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
10590 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
105a0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
105b0 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
105c0 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
105d0 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
105e0 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
105f0 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
10610 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
10620 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
10630 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
10640 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
10650 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
10660 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
10670 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
10680 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
10690 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
106a0 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
106b0 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
106c0 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
106d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
106e0 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
106f0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10700 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
10710 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10720 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
10730 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10740 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
10750 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
10760 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10770 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10780 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10790 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
107a0 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
107b0 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
107c0 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
107d0 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
107e0 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
107f0 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10800 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
10810 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
10820 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
10830 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
10840 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
10850 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
10860 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10870 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10880 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10890 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
108a0 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
108b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
108c0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
108d0 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
108e0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
108f0 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10900 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
10910 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
10920 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10930 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
10940 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
10950 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
10960 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10970 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10980 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
109a0 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
109b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
109c0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
109d0 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
109e0 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
109f0 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10a10 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
10a20 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
10a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a40 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
10a50 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
10a60 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10a70 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10a80 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10a90 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10aa0 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10ab0 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10ac0 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10ad0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10ae0 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10af0 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10b00 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
10b10 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
10b20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
10b30 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10b40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
10b50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10b60 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10b70 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10b80 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10b90 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10ba0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10bb0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10bc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10bd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10be0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
10bf0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10c00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
10c10 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
10c20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
10c30 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
10c40 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
10c50 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
10c60 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10c70 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10c80 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10c90 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10ca0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10cb0 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10cc0 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10cd0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10ce0 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10cf0 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10d00 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
10d10 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
10d20 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10d30 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
10d40 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
10d50 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
10d60 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10d70 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10d80 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10d90 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10da0 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10dc0 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10dd0 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10de0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10df0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10e00 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
10e10 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
10e20 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
10e30 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
10e40 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
10e50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
10e60 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10e70 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10e80 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10e90 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10ea0 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10ec0 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10ed0 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10ee0 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10ef0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10f00 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
10f10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10f20 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
10f30 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
10f40 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
10f50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10f60 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10f70 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10f80 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10f90 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10fa0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10fb0 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10fc0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10fd0 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10fe0 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10ff0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
11000 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
11010 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
11020 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
11030 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
11040 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
11050 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
11060 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
11070 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
11080 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11090 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
110a0 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
110b0 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
110c0 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
110d0 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
110e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
110f0 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
11100 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
11110 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
11120 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
11130 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
11140 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11150 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
11160 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
11170 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11180 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
11190 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
111a0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
111b0 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
111c0 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
111d0 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
111e0 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
111f0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
11200 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
11210 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11220 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
11230 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
11240 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
11250 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11260 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
11270 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
11280 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
11290 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
112a0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
112b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
112c0 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
112d0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
112e0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
112f0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11300 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
11310 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11320 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
11330 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11340 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
11350 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
11360 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11370 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
11380 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11390 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
113a0 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
113b0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
113c0 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
113d0 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
113e0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
113f0 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
11400 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
11410 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
11420 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
11430 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
11440 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
11450 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
11460 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
11470 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
11480 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
11490 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
114a0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
114b0 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
114c0 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
114d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
114e0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
114f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11500 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
11510 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
11520 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11530 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
11540 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
11550 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11560 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
11570 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
11580 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
11590 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
115a0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
115b0 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
115c0 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
115d0 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
115e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
115f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
11600 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
11610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11620 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
11630 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
11640 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
11650 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
11660 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
11670 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
11680 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
11690 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
116a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
116b0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
116c0 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
116d0 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
116e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
116f0 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
11700 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11710 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
11720 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
11730 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
11740 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
11750 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
11760 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11770 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11780 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11790 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
117a0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
117b0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
117c0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
117d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
117e0 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
117f0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11800 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
11810 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
11820 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
11830 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
11840 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11850 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
11860 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11870 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11880 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11890 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
118a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
118b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
118c0 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
118d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118e0 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
118f0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11900 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
11910 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
11920 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
11930 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
11940 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
11950 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
11960 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11970 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11980 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11990 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
119a0 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
119b0 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
119c0 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
119d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
119e0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
119f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11a00 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
11a10 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
11a20 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
11a30 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
11a40 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
11a50 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
11a60 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11a70 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11a80 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11a90 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11aa0 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11ab0 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11ac0 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11ad0 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11ae0 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11af0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11b00 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
11b10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11b20 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
11b30 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
11b40 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
11b50 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
11b60 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11b70 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11b80 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ba0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11bb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11bc0 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
11bd0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
11be0 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
11bf0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
11c00 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
11c10 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
11c20 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
11c30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11c40 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
11c50 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
11c60 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11c70 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11c80 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11c90 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11ca0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11cb0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11cc0 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11cd0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11ce0 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11cf0 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11d00 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
11d10 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11d20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
11d30 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
11d40 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
11d50 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
11d60 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11d70 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11d80 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11d90 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11da0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11db0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11dc0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11dd0 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11de0 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11df0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11e00 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
11e10 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
11e20 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
11e30 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
11e40 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11e50 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
11e60 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11e80 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11e90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11ea0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11eb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11ec0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11ed0 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11ee0 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11ef0 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
11f00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11f10 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
11f20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
11f30 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11f40 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
11f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
11f60 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11f70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11f80 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11f90 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11fb0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11fc0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
11fd0 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
11fe0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11ff0 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
12000 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
12010 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
12020 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
12030 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
12040 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
12050 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
12060 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
12070 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
12080 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
12090 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
120a0 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
120b0 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
120c0 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
120d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
120e0 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
120f0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
12100 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12110 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
12120 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
12130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
12140 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
12150 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
12160 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
12170 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12180 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12190 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
121a0 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
121b0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
121c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
121d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
121e0 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
121f0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
12200 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12210 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
12220 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
12230 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
12240 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
12250 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
12260 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
12270 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
12280 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
12290 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
122a0 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
122b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
122c0 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
122d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
122e0 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
122f0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
12300 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
12310 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
12320 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
12330 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
12340 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12350 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
12360 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
12370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12380 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
12390 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
123a0 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
123b0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
123c0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
123d0 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
123e0 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
123f0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
12400 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12410 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
12420 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
12430 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12440 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
12450 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
12460 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
12470 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12480 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
12490 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
124a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
124b0 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
124c0 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
124d0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
124e0 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
124f0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
12500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
12510 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12520 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
12530 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
12540 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12550 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12560 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12570 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
12580 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
12590 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
125b0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
125c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
125d0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
12600 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
12610 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12620 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
12630 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
12640 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
12650 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
12660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
12670 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
12680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
12690 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
126a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
126b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
126c0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
126d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
126e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
126f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12700 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
12710 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
12720 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
12730 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
12740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12750 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
12760 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12770 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12780 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12790 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
127a0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
127b0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
127c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
127d0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
127e0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
127f0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12800 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
12810 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12820 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
12830 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
12840 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
12850 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
12860 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12870 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12880 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12890 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
128a0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
128b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
128c0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
128d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
128e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
128f0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12900 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
12910 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
12920 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
12930 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12940 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12950 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
12960 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12970 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12980 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12990 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
129a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129b0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
129c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
129d0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
129e0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
129f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12a00 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
12a10 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
12a20 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
12a30 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
12a40 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
12a50 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
12a60 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12a70 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12a80 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12a90 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12aa0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12ab0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12ac0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12ad0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12ae0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12af0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12b00 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
12b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
12b20 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
12b30 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
12b40 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
12b50 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
12b60 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12b70 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12b80 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12b90 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12ba0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12bb0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12bc0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12be0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
12bf0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
12c00 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
12c10 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
12c20 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
12c30 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12c40 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12c50 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
12c60 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12c70 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12c80 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12c90 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12ca0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12cb0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12cc0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
12cd0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
12ce0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
12cf0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
12d00 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
12d10 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
12d20 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
12d30 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
12d40 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
12d50 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12d60 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12d70 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12d80 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12d90 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12da0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12db0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12dc0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
12dd0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
12de0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
12df0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
12e00 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
12e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12e20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
12e30 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
12e40 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
12e50 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12e60 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12e70 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12e80 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12e90 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12ea0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12eb0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12ec0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
12ed0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
12ee0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
12ef0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12f00 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
12f10 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
12f20 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
12f30 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12f40 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
12f60 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12f70 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12f80 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12f90 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12fa0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12fb0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12fc0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
12fd0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
12fe0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
12ff0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
13000 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13010 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
13020 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
13030 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
13040 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
13050 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
13060 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
13070 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
13080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
13090 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
130a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
130b0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
130c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
130d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
130e0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
130f0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
13100 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
13110 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
13120 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
13130 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
13140 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13150 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13160 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13170 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13180 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13190 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
131a0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
131b0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
131c0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
131d0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
131e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
131f0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
13200 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
13210 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
13220 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
13230 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
13240 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13250 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13260 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13270 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13280 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13290 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
132a0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
132b0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
132c0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
132d0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
132e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
132f0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
13300 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
13310 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
13320 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
13330 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
13340 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
13350 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
13360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13370 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
13380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13390 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
133a0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
133b0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
133c0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
133d0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
133e0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
133f0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
13400 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
13410 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
13420 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
13430 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
13440 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
13450 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
13460 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
13470 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
13480 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
13490 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
134a0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
134b0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
134c0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
134d0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
134e0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
134f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
13500 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
13510 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13520 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
13530 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
13540 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
13550 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
13560 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
13570 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
13580 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
13590 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
135a0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
135b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
135c0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
135d0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
135e0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
135f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13600 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
13610 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
13620 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
13630 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
13640 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
13650 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
13660 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
13670 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
13680 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
13690 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
136a0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
136b0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
136c0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
136d0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
136e0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
136f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
13700 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
13710 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13720 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
13730 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
13740 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
13750 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
13760 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13770 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13780 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13790 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
137a0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
137b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
137c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
137d0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
137e0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
137f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13800 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13810 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13820 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13830 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13840 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13850 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13870 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13880 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13890 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
138a0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
138b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
138c0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
138d0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
138e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
138f0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13900 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
13910 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13920 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
13930 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
13940 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
13950 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13960 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13970 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13980 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13990 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
139a0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
139b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
139c0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
139d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
139e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139f0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13a00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
13a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13a30 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13a40 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13a50 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13a60 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13a70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13a80 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13a90 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13aa0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13ab0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13ac0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13ad0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13ae0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13af0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13b00 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
13b10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13b20 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13b30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13b40 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13b50 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13b60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13b70 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13b80 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13b90 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13ba0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13bb0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13bc0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
13bd0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
13be0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13bf0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
13c00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13c10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
13c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13c30 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
13c40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13c50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c70 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c90 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13ca0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13cb0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13cc0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13cd0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13ce0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13cf0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
13d00 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
13d10 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
13d20 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
13d30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
13d40 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
13d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13d60 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13d80 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13d90 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13da0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13dc0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13dd0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
13de0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
13df0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
13e00 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
13e10 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
13e20 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
13e30 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
13e40 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
13e50 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
13e60 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13e70 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13e90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13ea0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13eb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13ec0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13ed0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13ee0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13ef0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13f00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
13f10 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
13f20 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
13f30 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
13f40 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13f50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13f60 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13f70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13f80 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13f90 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13fa0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13fb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13fc0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13fe0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14000 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
14010 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14020 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14030 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14040 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14050 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14060 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14070 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14080 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14090 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
140a0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
140b0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
140c0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
140d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
140e0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
140f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14100 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
14110 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
14120 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
14130 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14140 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14150 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14160 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14170 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14180 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14190 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
141a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
141b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
141c0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
141d0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
141e0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
141f0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
14200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14210 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
14220 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
14230 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
14240 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14260 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14270 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14280 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14290 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
142a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
142b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
142c0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
142d0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
142e0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
142f0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
14300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14360 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
14370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14380 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14390 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
143a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
143b0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
143c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
143e0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
143f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14400 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14420 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14430 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14440 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14450 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14460 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
14470 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14480 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
14490 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
144a0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
144b0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
144c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
144d0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
144e0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
144f0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
14500 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14510 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
14520 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14530 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
14540 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
14550 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
14560 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
14570 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
14580 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14590 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
145a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
145b0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
145c0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
145d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
145e0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
145f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14600 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14620 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14630 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14640 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14650 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
14660 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
14670 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14680 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14690 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
146a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
146b0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
146c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
146d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
146e0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
146f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14700 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14710 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
14720 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
14730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14740 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
14750 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
14760 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14770 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14790 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
147a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
147b0 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
147c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
147d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
147e0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
147f0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14800 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
14810 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
14820 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14830 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
14840 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
14850 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
14860 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14870 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14880 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14890 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
148a0 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
148b0 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
148c0 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
148d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
148e0 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
148f0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14900 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
14910 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
14920 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
14930 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
14940 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
14950 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
14960 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14970 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14980 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14990 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
149a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
149c0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
149d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
149e0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
149f0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14a00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
14a10 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
14a20 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14a30 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
14a40 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14a50 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
14a60 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14a70 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14a80 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14a90 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14aa0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14ab0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14ac0 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14ad0 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14ae0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14af0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14b00 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
14b10 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
14b20 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14b30 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
14b40 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14b50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14b60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14b70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14b80 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14b90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14ba0 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14bb0 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14bd0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
14be0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
14bf0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
14c00 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
14c10 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
14c20 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
14c30 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
14c40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
14c50 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14c60 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14c70 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14c80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14c90 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14ca0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14cb0 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14cc0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
14cd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14ce0 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
14cf0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
14d00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14d10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14d20 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14d30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d60 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14d70 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14d80 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14d90 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14da0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14db0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14dc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
14dd0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
14de0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14df0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14e00 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
14e10 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
14e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14e30 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14e40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
14e50 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
14e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e70 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14e80 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14e90 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14ea0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14eb0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14ec0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
14ed0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
14ee0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14ef0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14f00 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
14f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
14f20 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
14f30 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
14f40 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
14f50 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
14f60 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14f70 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14f80 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14f90 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14fa0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14fb0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14fc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
14fd0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
14fe0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
14ff0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
15000 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
15010 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
15020 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15030 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
15040 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
15050 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
15060 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
15070 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
15080 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
15090 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
150a0 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
150b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
150c0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
150d0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
150e0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
150f0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
15100 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
15110 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
15120 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
15130 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
15140 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
15150 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
15160 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
15170 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
15180 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
15190 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
151a0 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
151b0 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
151c0 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
151d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
151e0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
151f0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
15200 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
15210 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
15220 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
15230 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
15240 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
15250 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
15260 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
15270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15280 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
15290 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
152a0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
152b0 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
152c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
152d0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
152e0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
152f0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
15300 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
15310 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
15320 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
15330 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
15340 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
15350 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
15360 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15370 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
15380 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
15390 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
153a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
153b0 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
153c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
153d0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
153e0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
153f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15400 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
15410 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
15420 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
15440 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
15450 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
15460 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
15470 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15480 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
15490 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
154a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
154b0 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
154c0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
154d0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
154e0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
154f0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15500 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
15510 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15520 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
15530 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
15540 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
15550 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
15560 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
15570 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
15580 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
15590 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
155a0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
155b0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
155c0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
155d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
155e0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
155f0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
15600 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
15610 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15620 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
15630 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
15640 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
15650 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
15660 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
15670 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15680 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
15690 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
156a0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
156b0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
156c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
156d0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
156e0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
156f0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
15700 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
15710 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
15730 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
15740 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
15750 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
15760 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15770 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15780 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15790 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
157a0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
157b0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
157c0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
157d0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
157e0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
157f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15800 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
15810 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
15820 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15830 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15840 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15850 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15860 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15870 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15880 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15890 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
158a0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
158b0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
158c0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
158d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158e0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
158f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15920 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15930 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15940 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15950 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15960 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15970 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15980 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15990 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
159a0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
159b0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
159c0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
159d0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
159e0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
159f0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15a00 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
15a10 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15a20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15a30 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15a40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15a50 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15a60 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15a70 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15a80 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15a90 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15aa0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15ab0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15ac0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15ad0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15ae0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15af0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15b00 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15b10 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15b20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15b30 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15b40 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15b50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15b60 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15b70 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15b90 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15ba0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15bd0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15be0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15bf0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15c00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15c10 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
15c20 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15c30 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15c40 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15c50 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15c70 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15c80 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15c90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15ca0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15cb0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15cc0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15cd0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15ce0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15cf0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15d00 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
15d10 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
15d20 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
15d30 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15d40 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15d50 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15d60 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15d70 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15d80 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15d90 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15da0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15db0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15dc0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15dd0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15de0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15df0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15e00 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
15e10 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
15e20 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15e30 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15e40 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15e50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15e60 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15e70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15e80 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15ea0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15eb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15ec0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15ed0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15ee0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
15ef0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15f00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15f10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15f20 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
15f30 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15f40 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15f50 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
15f60 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15f70 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15f80 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15f90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15fb0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15fc0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15fd0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
15fe0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
15ff0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16000 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
16010 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
16020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
16030 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
16040 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
16050 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
16060 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
16070 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
16080 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16090 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
160a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
160b0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
160c0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
160d0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
160e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
160f0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
16100 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
16110 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16120 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
16130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16140 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
16150 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16170 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16190 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
161a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
161b0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
161c0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
161d0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
161e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
161f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
16200 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
16210 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16220 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
16230 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
16240 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
16250 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16260 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
16270 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16280 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
16290 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
162a0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
162b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
162c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
162d0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
162e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
162f0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
16300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16310 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16320 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16330 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
16340 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
16350 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
16360 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
16370 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
16380 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
163a0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
163b0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
163c0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
163d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
163e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
163f0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
16400 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
16410 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
16420 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16430 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
16440 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
16450 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
16460 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
16470 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
16480 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
16490 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
164a0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
164b0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
164c0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
164d0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
164e0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
164f0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
16500 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
16510 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
16520 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
16530 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
16540 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
16550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
16560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
16570 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
16580 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
16590 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
165a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
165b0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
165c0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
165d0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
165e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
165f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
16600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
16610 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
16620 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
16630 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
16640 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
16650 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
16660 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
16670 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
16680 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16690 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
166a0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
166b0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
166c0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
166d0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
166e0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
166f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16700 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
16710 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
16720 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
16730 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
16740 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
16750 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
16760 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16770 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16780 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16790 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
167a0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
167b0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
167c0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
167d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
167e0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
167f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16800 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
16810 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
16820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16830 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16840 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16850 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16860 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16880 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16890 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
168a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
168b0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
168c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
168d0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
168e0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
168f0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16900 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
16910 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
16920 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16930 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16940 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16950 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16960 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16970 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16980 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16990 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
169a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
169b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
169c0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
169d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
169e0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
169f0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16a00 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
16a10 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16a20 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16a30 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16a40 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16a50 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16a60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16a70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16a80 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16a90 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16aa0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16ab0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16ac0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16ad0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16ae0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16af0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16b00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16b10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16b20 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16b30 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16b40 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16b50 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16b60 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16b70 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16b80 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16ba0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16bb0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16bd0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16be0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16bf0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16c00 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
16c10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16c20 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16c30 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16c40 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16c50 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16c60 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16c70 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16c80 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16c90 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16ca0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16cb0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16cc0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16cd0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16ce0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
16d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
16d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
16d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
16de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
16df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
16e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
16e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
16e20 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
16e30 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
16e40 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
16e50 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
16e60 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16e70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16e80 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16e90 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16ea0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16eb0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16ec0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16ed0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16ee0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16ef0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
16f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16f10 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
16f20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16f30 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
16f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16f50 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
16f60 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16f70 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16f80 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16f90 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16fa0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16fb0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16fc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16fd0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
16fe0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
16ff0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17000 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
17010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17020 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
17030 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
17040 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
17050 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17060 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
17070 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
17080 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
17090 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
170a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
170b0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
170c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
170d0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
170e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
170f0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
17100 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
17110 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
17120 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
17130 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
17140 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
17150 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
17160 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
17170 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
17180 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
17190 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
171a0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
171b0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
171c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
171d0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
171e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171f0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
17200 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17210 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
17220 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
17230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
17240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
17250 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
17260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
17270 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
17280 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
17290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
172a0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
172b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
172c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
172d0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
172e0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
172f0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
17300 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17310 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
17320 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
17330 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
17340 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
17350 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
17360 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
17370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
17380 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
17390 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
173a0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
173b0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
173c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
173d0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
173e0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
173f0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
17400 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
17410 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
17420 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
17430 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17440 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
17450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17460 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
17470 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
17480 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
17490 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
174a0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
174b0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
174c0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
174d0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
174e0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
174f0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
17500 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17510 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
17520 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
17530 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
17540 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
17550 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
17560 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
17570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17580 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
17590 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
175a0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
175b0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
175c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
175d0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
175e0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
175f0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
17600 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
17610 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
17620 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
17630 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
17640 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
17650 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
17660 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
17670 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
17680 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
17690 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
176a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
176b0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
176c0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
176d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
176e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
176f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
17700 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
17710 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
17720 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
17730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17740 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
17750 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17760 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17770 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17780 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17790 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
177a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
177b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
177c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
177d0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
177e0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
177f0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17800 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
17810 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
17820 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17830 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17840 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17850 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17860 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17870 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17880 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17890 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
178a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
178b0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
178c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
178d0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
178e0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
178f0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17900 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17910 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17920 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17930 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17940 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17950 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17960 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17970 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17980 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17990 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
179a0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
179b0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
179c0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
179d0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
179e0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
179f0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17a00 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
17a10 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
17a20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17a30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17a40 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17a50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17a60 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17a70 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17a80 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17a90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17aa0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17ab0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17ac0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17ad0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17ae0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17af0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17b00 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
17b10 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
17b20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17b30 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17b40 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17b50 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
17b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17b70 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17b80 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17b90 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17ba0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17bb0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17bc0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17bd0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17be0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17bf0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17c00 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
17c10 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
17c20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
17c30 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
17c40 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
17c50 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
17c60 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17c70 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17c80 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17ca0 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17cb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17cc0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
17cd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17ce0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17cf0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
17d00 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17d10 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17d20 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
17d30 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17d40 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
17d50 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
17d60 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17d70 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17d80 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17d90 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17da0 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17db0 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17dc0 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
17dd0 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
17de0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
17df0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
17e00 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
17e10 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
17e20 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
17e30 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
17e40 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
17e50 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
17e60 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17e70 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17e80 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17e90 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17ea0 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17eb0 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17ec0 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
17ed0 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
17ee0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
17ef0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
17f00 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
17f10 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
17f20 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
17f30 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
17f40 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
17f50 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
17f60 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  me option..**.**
17f70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17f80 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d  _SORTERREF_SIZE]
17f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17fa0 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
17fb0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  _SIZE.** <dd>The
17fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17fd0 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70  ORTERREF_SIZE op
17fe0 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
17ff0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18000 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29  ** of type (int)
18010 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65   - the new value
18020 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72   of the sorter-r
18030 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68  eference size th
18040 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61  reshold..** Usua
18050 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65  lly, when SQLite
18060 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61   uses an externa
18070 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20  l sort to order 
18080 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e  records accordin
18090 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52  g.** to an ORDER
180a0 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20   BY clause, all 
180b0 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20  fields required 
180c0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72  by the caller ar
180d0 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65  e present in the
180e0 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72  .** sorted recor
180f0 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  ds. However, if 
18100 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18110 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64  s based on the d
18120 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20  eclared type.** 
18130 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  of a table colum
18140 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65  n that its value
18150 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
18160 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20  be very large - 
18170 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74  larger.** than t
18180 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f  he configured so
18190 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73  rter-reference s
181a0 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20  ize threshold - 
181b0 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65  then a reference
181c0 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e  .** is stored in
181d0 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63   each sorted rec
181e0 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75  ord and the requ
181f0 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ired column valu
18200 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f  es loaded.** fro
18210 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  m the database a
18220 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65  s records are re
18230 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64  turned in sorted
18240 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61   order. The defa
18250 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ult.** value for
18260 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
18270 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69  to never use thi
18280 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20  s optimization. 
18290 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a  Specifying a .**
182a0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
182b0 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
182c0 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66  restores the def
182d0 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a  ault behaviour..
182e0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  ** This option i
182f0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
18300 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
18310 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
18320 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
18330 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e  E_SORTER_REFEREN
18340 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CES] compile-tim
18350 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64  e option..** </d
18360 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18380 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18390 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
183a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
183b0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
183c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
183d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
183e0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
183f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18400 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18410 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
18420 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18430 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18450 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18460 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18470 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18490 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
184a0 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72   6  /* No longer
184b0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
184c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
184d0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
184e0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
184f0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
18500 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18510 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
18520 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18530 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
18540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18550 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
18560 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
18570 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
18590 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
185a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
185b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
185c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185d0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
185e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
185f0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
18600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
18610 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
18620 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
18630 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
18640 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
18650 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
18660 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
18670 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18690 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
186a0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
186b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
186c0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
186d0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
186e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
186f0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
18700 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
18710 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18730 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
18740 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18760 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
18770 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18780 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
187a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
187b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
187c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
187d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
187e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
187f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
18800 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18810 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18820 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
18830 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
18840 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
18860 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
18870 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
18880 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
188a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
188b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
188c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
188d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
188e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
188f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
18900 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
18910 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18920 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
18930 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
18940 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
18950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18960 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18970 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
18980 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
18990 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
189a0 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
189b0 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20  LLOC        27  
189c0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
189d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189e0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
189f0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69  ZE      28  /* i
18a00 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
18a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
18a20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18a30 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
18a40 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
18a50 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
18a60 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
18a70 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
18a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
18a90 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
18aa0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18ac0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18ad0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
18ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
18af0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18b00 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
18b10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18b20 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
18b30 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
18b40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
18b50 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
18b60 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
18b70 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
18b80 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
18b90 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
18ba0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
18bb0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
18bc0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
18bd0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
18be0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18bf0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
18c00 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
18c10 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
18c20 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
18c30 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
18c40 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
18c50 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
18c60 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
18c70 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  >.** [[SQLITE_DB
18c80 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18c90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
18ca0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18cb0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
18cc0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
18cd0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
18ce0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
18cf0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
18d00 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
18d10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18d20 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
18d30 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
18d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
18d50 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18d60 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
18d70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
18d80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18d90 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
18da0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18db0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
18dc0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
18dd0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
18de0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
18df0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18e00 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18e10 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18e20 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
18e30 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
18e40 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
18e50 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
18e60 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
18e70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
18e80 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18e90 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
18ea0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
18eb0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
18ec0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
18ed0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
18ee0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
18ef0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18f00 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18f10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18f20 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
18f30 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
18f40 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
18f50 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
18f60 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
18f70 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
18f80 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18f90 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
18fa0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
18fb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18fc0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
18fd0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18fe0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
18ff0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
19000 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
19010 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
19020 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
19030 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
19040 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
19050 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
19060 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
19070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19080 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
19090 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
190a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
190b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
190c0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
190d0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
190e0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
190f0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
19100 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
19110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
19120 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
19130 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
19140 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
19150 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
19160 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
19170 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
19180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
19190 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
191a0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
191b0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
191c0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
191d0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
191e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
191f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
19200 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
19210 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a  G_ENABLE_FKEY]].
19220 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19230 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
19240 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
19250 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19260 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19270 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
19280 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
19290 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
192a0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
192b0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
192c0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
192d0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
192e0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
192f0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19300 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19310 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
19320 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
19330 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
19340 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
19350 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
19360 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
19370 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
19380 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19390 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
193a0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
193b0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
193c0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
193d0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
193e0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
193f0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
19400 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
19410 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19420 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
19430 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
19440 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
19450 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19460 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19470 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
19490 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
194a0 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a  BLE_TRIGGER]].**
194b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
194c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
194d0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
194e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
194f0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19500 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
19510 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
19520 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
19530 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
19540 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
19550 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
19560 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
19570 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
19580 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
19590 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
195a0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
195b0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
195c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
195d0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
195e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
195f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19600 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19610 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19620 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19630 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19640 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
19650 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
19660 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
19670 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19680 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19690 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
196a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
196b0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
196c0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
196d0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
196e0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
196f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
19700 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19710 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 5d  _FTS3_TOKENIZER]
19720 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
19730 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19740 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
19750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19760 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19770 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19780 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
19790 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
197a0 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
197b0 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
197c0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
197d0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
197e0 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
197f0 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
19800 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
19810 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19820 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19830 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19840 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19850 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19860 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
19870 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
19880 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
19890 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
198a0 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
198b0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
198c0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
198d0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
198e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
198f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19900 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19910 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19920 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19930 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
19940 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
19950 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
19960 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
19970 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
19980 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19990 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
199a0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
199b0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
199c0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
199d0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
199e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
199f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19a00 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
19a10 53 49 4f 4e 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SION]].** <dt>SQ
19a20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19a30 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
19a40 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ION</dt>.** <dd>
19a50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
19a60 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19a70 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b  or disable the [
19a80 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
19a90 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74  ension()].** int
19aa0 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65  erface independe
19ab0 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61  ntly of the [loa
19ac0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
19ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
19ae0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
19af0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
19b00 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65  on()] API enable
19b10 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f  s or disables bo
19b20 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  th the.** C-API 
19b30 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
19b40 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74  tension()] and t
19b50 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19b60 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
19b70 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  )]..** There sho
19b80 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
19b90 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19ba0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72  .** When the fir
19bb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19bc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19bd0 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68   1, then only th
19be0 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e  e C-API is.** en
19bf0 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51  abled and the SQ
19c00 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69  L function remai
19c10 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66  ns disabled.  If
19c20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19c30 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
19c40 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
19c50 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
19c60 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
19c70 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
19c80 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
19c90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19ca0 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
19cb0 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
19cc0 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
19cd0 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
19ce0 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
19cf0 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
19d00 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19d10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19d20 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19d30 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19d40 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19d50 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
19d60 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19d70 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
19d80 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
19d90 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
19da0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19dc0 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
19dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19de0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
19df0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
19e00 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
19e10 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
19e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
19e30 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 5d 5d  FIG_MAINDBNAME]]
19e40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19e50 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
19e60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19e70 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19e80 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
19e90 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
19ea0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
19eb0 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
19ec0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19ed0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19ee0 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
19ef0 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
19f00 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
19f10 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
19f20 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
19f30 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
19f40 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
19f50 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
19f60 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
19f70 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
19f80 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
19f90 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
19fa0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
19fb0 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
19fc0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19fd0 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19fe0 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
19ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
1a000 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
1a010 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1a020 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
1a030 5f 43 4c 4f 53 45 5d 5d 20 0a 2a 2a 20 3c 64 74  _CLOSE]] .** <dt
1a040 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a050 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
1a060 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55  E</dt>.** <dd> U
1a070 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64  sually, when a d
1a080 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d  atabase in wal m
1a090 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  ode is closed or
1a0a0 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61   detached from a
1a0b0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61   .** database ha
1a0c0 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65  ndle, SQLite che
1a0d0 63 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c  cks if this will
1a0e0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72 65   mean that there
1a0f0 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20   are now no .** 
1a100 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61  connections at a
1a110 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ll to the databa
1a120 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65  se. If so, it pe
1a130 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f  rforms a checkpo
1a140 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  int .** operatio
1a150 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67  n before closing
1a160 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1a170 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79   This option may
1a180 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f   be used to.** o
1a190 76 65 72 72 69 64 65 20 74 68 69 73 20 62 65 68  verride this beh
1a1a0 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73  aviour. The firs
1a1b0 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  t parameter pass
1a1c0 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61  ed to this opera
1a1d0 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  tion.** is an in
1a1e0 74 65 67 65 72 20 2d 20 70 6f 73 69 74 69 76 65  teger - positive
1a1f0 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63   to disable chec
1a200 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
1a210 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a  , or zero (the.*
1a220 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e  * default) to en
1a230 61 62 6c 65 20 74 68 65 6d 2c 20 61 6e 64 20 6e  able them, and n
1a240 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
1a250 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
1a260 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
1a270 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a280 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1a290 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e  an integer.** in
1a2a0 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74  to which is writ
1a2b0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1a2c0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 63  dicate whether c
1a2d0 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
1a2e0 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e  ose.** have been
1a2f0 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66   disabled - 0 if
1a300 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69   they are not di
1a310 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65  sabled, 1 if the
1a320 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  y are..** </dd>.
1a330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1a340 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51  BCONFIG_ENABLE_Q
1a350 50 53 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  PSG]] <dt>SQLITE
1a360 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a370 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _QPSG</dt>.** <d
1a380 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44  d>^(The SQLITE_D
1a390 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51  BCONFIG_ENABLE_Q
1a3a0 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76  PSG option activ
1a3b0 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61  ates or deactiva
1a3c0 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72  tes.** the [quer
1a3d0 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c  y planner stabil
1a3e0 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28  ity guarantee] (
1a3f0 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65  QPSG).  When the
1a400 20 51 50 53 47 20 69 73 20 61 63 74 69 76 65 2c   QPSG is active,
1a410 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  .** a single SQL
1a420 20 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74   query statement
1a430 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65   will always use
1a440 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
1a450 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  thm regardless.*
1a460 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b  * of values of [
1a470 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
1a480 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20 64 69  ].)^ The QPSG di
1a490 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72  sables some quer
1a4a0 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a  y optimizations.
1a4b0 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20  ** that look at 
1a4c0 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f  the values of bo
1a4d0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20  und parameters, 
1a4e0 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73  which can make s
1a4f0 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73  ome queries.** s
1a500 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68 65 20  lower.  But the 
1a510 51 50 53 47 20 68 61 73 20 74 68 65 20 61 64 76  QPSG has the adv
1a520 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70  antage of more p
1a530 72 65 64 69 63 74 61 62 6c 65 20 62 65 68 61 76  redictable behav
1a540 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68  ior.  With.** th
1a550 65 20 51 50 53 47 20 61 63 74 69 76 65 2c 20 53  e QPSG active, S
1a560 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
1a570 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 71  s use the same q
1a580 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65  uery plan in the
1a590 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73   field as.** was
1a5a0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
1a5b0 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e  ting in the lab.
1a5c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1a5d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 73  gument to this s
1a5e0 65 74 74 69 6e 67 20 69 73 20 61 6e 20 69 6e 74  etting is an int
1a5f0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
1a600 74 6f 20 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74  to disable .** t
1a610 68 65 20 51 50 53 47 2c 20 70 6f 73 69 74 69 76  he QPSG, positiv
1a620 65 20 74 6f 20 65 6e 61 62 6c 65 20 51 50 53 47  e to enable QPSG
1a630 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  , or negative to
1a640 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1a650 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
1a660 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a670 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a680 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a690 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
1a6a0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a6b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a6c0 74 68 65 72 20 74 68 65 20 51 50 53 47 20 69 73  ther the QPSG is
1a6d0 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
1a6e0 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
1a6f0 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20  g this call..** 
1a700 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a710 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52  LITE_DBCONFIG_TR
1a720 49 47 47 45 52 5f 45 51 50 5d 5d 20 3c 64 74 3e  IGGER_EQP]] <dt>
1a730 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a740 54 52 49 47 47 45 52 5f 45 51 50 3c 2f 64 74 3e  TRIGGER_EQP</dt>
1a750 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 65 66 61  .** <dd> By defa
1a760 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 75 74 20  ult, the output 
1a770 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59  of EXPLAIN QUERY
1a780 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73 20 64   PLAN commands d
1a790 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c  oes not .** incl
1a7a0 75 64 65 20 6f 75 74 70 75 74 20 66 6f 72 20 61  ude output for a
1a7b0 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65  ny operations pe
1a7c0 72 66 6f 72 6d 65 64 20 62 79 20 74 72 69 67 67  rformed by trigg
1a7d0 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 69  er programs. Thi
1a7e0 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  s.** option is u
1a7f0 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 63 6c  sed to set or cl
1a800 65 61 72 20 28 74 68 65 20 64 65 66 61 75 6c 74  ear (the default
1a810 29 20 61 20 66 6c 61 67 20 74 68 61 74 20 67 6f  ) a flag that go
1a820 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a 20 62 65  verns this.** be
1a830 68 61 76 69 6f 72 2e 20 54 68 65 20 66 69 72 73  havior. The firs
1a840 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  t parameter pass
1a850 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61  ed to this opera
1a860 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 74 65 67  tion is an integ
1a870 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 74 69 76 65  er -.** positive
1a880 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 74 70 75   to enable outpu
1a890 74 20 66 6f 72 20 74 72 69 67 67 65 72 20 70 72  t for trigger pr
1a8a0 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 72 6f 20  ograms, or zero 
1a8b0 74 6f 20 64 69 73 61 62 6c 65 20 69 74 2c 0a 2a  to disable it,.*
1a8c0 2a 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  * or negative to
1a8d0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1a8e0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
1a8f0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a900 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a910 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a920 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
1a930 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20 6f 72 20  ritten .** 0 or 
1a940 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a950 65 74 68 65 72 20 6f 75 74 70 75 74 2d 66 6f 72  ether output-for
1a960 2d 74 72 69 67 67 65 72 73 20 68 61 73 20 62 65  -triggers has be
1a970 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
1a980 69 66 20 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  if .** it is not
1a990 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
1a9a0 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64  it is.  .** </dd
1a9b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1a9c0 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1a9d0 44 41 54 41 42 41 53 45 5d 5d 20 3c 64 74 3e 53  DATABASE]] <dt>S
1a9e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1a9f0 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c 2f 64  ESET_DATABASE</d
1aa00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74 20 74  t>.** <dd> Set t
1aa10 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1aa20 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53  IG_RESET_DATABAS
1aa30 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65 6e 20  E flag and then 
1aa40 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d 5d 20  run.** [VACUUM] 
1aa50 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 73 65  in order to rese
1aa60 74 20 61 20 64 61 74 61 62 61 73 65 20 62 61 63  t a database bac
1aa70 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 64 61  k to an empty da
1aa80 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68 20 6e  tabase.** with n
1aa90 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e 6f 20  o schema and no 
1aaa0 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66 6f 6c  content. The fol
1aab0 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73 20 77  lowing process w
1aac0 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a 2a 2a  orks even for.**
1aad0 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75 70 74   a badly corrupt
1aae0 65 64 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ed database file
1aaf0 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ol>.** <li
1ab00 3e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  > If the databas
1ab10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ab20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20 6d 61  newly opened, ma
1ab30 6b 65 20 73 75 72 65 20 69 74 20 68 61 73 20 72  ke sure it has r
1ab40 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ead the.**      
1ab50 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1ab60 62 79 20 70 72 65 70 61 72 69 6e 67 20 74 68 65  by preparing the
1ab70 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73 6f 6d  n discarding som
1ab80 65 20 71 75 65 72 79 20 61 67 61 69 6e 73 74 20  e query against 
1ab90 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61  the.**      data
1aba0 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69 6e 67  base, or calling
1abb0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
1abc0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 29  olumn_metadata()
1abd0 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79 0a 2a  , ignoring any.*
1abe0 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e 20 20  *      errors.  
1abf0 54 68 69 73 20 73 74 65 70 20 69 73 20 6f 6e 6c  This step is onl
1ac00 79 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 74  y necessary if t
1ac10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1ac20 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70 0a 2a  esires to keep.*
1ac30 2a 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62  *      the datab
1ac40 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20  ase in WAL mode 
1ac50 61 66 74 65 72 20 74 68 65 20 72 65 73 65 74 20  after the reset 
1ac60 69 66 20 69 74 20 77 61 73 20 69 6e 20 57 41 4c  if it was in WAL
1ac70 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a 2a 20   mode before.** 
1ac80 20 20 20 20 20 74 68 65 20 72 65 73 65 74 2e 20       the reset. 
1ac90 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65   .** <li> sqlite
1aca0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1acb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1acc0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1acd0 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b  1, 0);.** <li> [
1ace0 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28 64 62  sqlite3_exec](db
1acf0 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20 30 2c  , "[VACUUM]", 0,
1ad00 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20   0, 0);.** <li> 
1ad10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
1ad20 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 43  g(db, SQLITE_DBC
1ad30 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1ad40 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  BASE, 0, 0);.** 
1ad50 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75 73 65  </ol>.** Because
1ad60 20 72 65 73 65 74 74 69 6e 67 20 61 20 64 61 74   resetting a dat
1ad70 61 62 61 73 65 20 69 73 20 64 65 73 74 72 75 63  abase is destruc
1ad80 74 69 76 65 20 61 6e 64 20 69 72 72 65 76 65 72  tive and irrever
1ad90 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20 70 72  sible, the.** pr
1ada0 6f 63 65 73 73 20 72 65 71 75 69 72 65 73 20 74  ocess requires t
1adb0 68 65 20 75 73 65 20 6f 66 20 74 68 69 73 20 6f  he use of this o
1adc0 62 73 63 75 72 65 20 41 50 49 20 61 6e 64 20 6d  bscure API and m
1add0 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20 74 6f  ultiple steps to
1ade0 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72 65 20   help.** ensure 
1adf0 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
1ae00 20 68 61 70 70 65 6e 20 62 79 20 61 63 63 69 64   happen by accid
1ae10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ent..**.** [[SQL
1ae20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1ae30 45 4e 53 49 56 45 5d 5d 20 3c 64 74 3e 53 51 4c  ENSIVE]] <dt>SQL
1ae40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1ae50 45 4e 53 49 56 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSIVE</dt>.** <
1ae60 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42  dd>The SQLITE_DB
1ae70 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45  CONFIG_DEFENSIVE
1ae80 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
1ae90 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
1aea0 20 74 68 65 0a 2a 2a 20 22 64 65 66 65 6e 73 69   the.** "defensi
1aeb0 76 65 22 20 66 6c 61 67 20 66 6f 72 20 61 20 64  ve" flag for a d
1aec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aed0 6f 6e 2e 20 20 57 68 65 6e 20 74 68 65 20 64 65  on.  When the de
1aee0 66 65 6e 73 69 76 65 0a 2a 2a 20 66 6c 61 67 20  fensive.** flag 
1aef0 69 73 20 65 6e 61 62 6c 65 64 2c 20 6c 61 6e 67  is enabled, lang
1af00 75 61 67 65 20 66 65 61 74 75 72 65 73 20 74 68  uage features th
1af10 61 74 20 61 6c 6c 6f 77 20 6f 72 64 69 6e 61 72  at allow ordinar
1af20 79 20 53 51 4c 20 74 6f 20 0a 2a 2a 20 64 65 6c  y SQL to .** del
1af30 69 62 65 72 61 74 65 6c 79 20 63 6f 72 72 75 70  iberately corrup
1af40 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
1af50 69 6c 65 20 61 72 65 20 64 69 73 61 62 6c 65 64  ile are disabled
1af60 2e 20 20 54 68 65 20 64 69 73 61 62 6c 65 64 0a  .  The disabled.
1af70 2a 2a 20 66 65 61 74 75 72 65 73 20 69 6e 63 6c  ** features incl
1af80 75 64 65 20 62 75 74 20 61 72 65 20 6e 6f 74 20  ude but are not 
1af90 6c 69 6d 69 74 65 64 20 74 6f 20 74 68 65 20 66  limited to the f
1afa0 6f 6c 6c 6f 77 69 6e 67 3a 0a 2a 2a 20 3c 75 6c  ollowing:.** <ul
1afb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 5b 50  >.** <li> The [P
1afc0 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73  RAGMA writable_s
1afd0 63 68 65 6d 61 3d 4f 4e 5d 20 73 74 61 74 65 6d  chema=ON] statem
1afe0 65 6e 74 2e 0a 2a 2a 20 3c 6c 69 3e 20 57 72 69  ent..** <li> Wri
1aff0 74 65 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  tes to the [sqli
1b000 74 65 5f 64 62 70 61 67 65 5d 20 76 69 72 74 75  te_dbpage] virtu
1b010 61 6c 20 74 61 62 6c 65 2e 0a 2a 2a 20 3c 6c 69  al table..** <li
1b020 3e 20 44 69 72 65 63 74 20 77 72 69 74 65 73 20  > Direct writes 
1b030 74 6f 20 5b 73 68 61 64 6f 77 20 74 61 62 6c 65  to [shadow table
1b040 73 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  s]..** </ul>.** 
1b050 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1b060 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b070 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
1b080 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
1b090 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
1b0a0 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
1b0b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
1b0c0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
1b0d0 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
1b0e0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
1b0f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b100 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
1b110 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
1b120 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b140 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
1b150 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
1b160 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
1b170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b180 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1b190 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
1b1a0 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
1b1b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b1c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1b1d0 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
1b1e0 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
1b1f0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b200 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
1b210 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
1b220 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
1b230 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b240 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b250 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
1b260 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
1b270 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b280 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b290 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20  G_TRIGGER_EQP   
1b2a0 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20          1008 /* 
1b2b0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b2c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b2d0 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1b2e0 53 45 20 20 20 20 20 20 20 20 31 30 30 39 20 2f  SE        1009 /
1b2f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b310 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 20  ONFIG_DEFENSIVE 
1b320 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31 30              1010
1b330 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b340 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b350 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20  BCONFIG_MAX     
1b360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1b370 31 30 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42  10 /* Largest DB
1b380 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  CONFIG */../*.**
1b390 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1b3a0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1b3b0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1b3c0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1b3d0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b3e0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1b3f0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1b400 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1b410 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1b420 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b430 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1b440 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1b450 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1b460 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1b470 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1b480 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1b490 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1b4a0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1b4b0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
1b4c0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
1b4d0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1b4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1b4f0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1b500 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b510 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
1b520 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
1b530 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
1b540 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
1b550 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
1b560 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
1b570 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
1b580 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
1b590 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
1b5a0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
1b5b0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
1b5c0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
1b5d0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
1b5e0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
1b5f0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
1b600 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
1b610 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
1b620 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
1b630 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1b640 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
1b650 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
1b660 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
1b670 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
1b680 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
1b690 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
1b6a0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
1b6b0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
1b6c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b6d0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b6e0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
1b6f0 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
1b700 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
1b710 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
1b720 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
1b730 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
1b740 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
1b750 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
1b760 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
1b770 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
1b780 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
1b790 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
1b7a0 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
1b7b0 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
1b7c0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
1b7d0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1b7e0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1b7f0 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
1b800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b810 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
1b820 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b830 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1b840 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
1b850 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
1b860 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
1b870 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
1b880 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
1b890 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
1b8a0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b8b0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1b8c0 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
1b8d0 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1b8f0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b900 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
1b910 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1b920 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1b930 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
1b940 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
1b950 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
1b960 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
1b970 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
1b980 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
1b990 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
1b9a0 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
1b9b0 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
1b9c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
1b9d0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b9e0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
1b9f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1ba00 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
1ba10 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
1ba20 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
1ba30 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
1ba40 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
1ba50 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1ba60 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
1ba70 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
1ba80 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
1ba90 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
1baa0 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
1bab0 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
1bac0 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
1bad0 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
1bae0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1baf0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
1bb00 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
1bb10 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
1bb20 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
1bb30 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1bb40 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1bb50 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
1bb60 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
1bb70 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1bb80 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1bb90 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
1bba0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
1bbb0 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
1bbc0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1bbd0 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
1bbe0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1bbf0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1bc00 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1bc10 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1bc20 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
1bc30 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
1bc40 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
1bc50 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
1bc60 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1bc70 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
1bc80 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
1bc90 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
1bca0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1bcb0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1bcc0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
1bcd0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
1bce0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
1bcf0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
1bd00 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
1bd10 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
1bd20 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
1bd30 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
1bd40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1bd50 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
1bd60 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
1bd70 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
1bd80 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
1bd90 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
1bda0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
1bdb0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
1bdc0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
1bdd0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
1bde0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
1bdf0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
1be00 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
1be10 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
1be20 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
1be30 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1be40 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
1be50 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
1be60 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1be70 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
1be80 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
1be90 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
1bea0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
1beb0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
1bec0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
1bed0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
1bee0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
1bef0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
1bf00 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1bf10 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
1bf20 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
1bf30 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
1bf40 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1bf50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1bf60 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1bf70 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
1bf80 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
1bf90 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
1bfa0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1bfb0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
1bfc0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1bfd0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1bfe0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1bff0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
1c000 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
1c010 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
1c020 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
1c030 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1c040 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1c050 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
1c060 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1c070 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
1c080 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
1c090 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
1c0a0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1c0b0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
1c0c0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1c0d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1c0e0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c0f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1c100 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1c110 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1c120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c130 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c140 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1c150 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1c160 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1c170 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1c180 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1c190 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1c1a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1c1b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1c1c0 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1c1d0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1c1e0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1c1f0 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
1c200 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1c210 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1c220 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
1c230 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1c240 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1c250 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1c260 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1c270 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c280 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1c290 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1c2a0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1c2b0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1c2c0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1c2d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1c2e0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1c2f0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1c300 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1c310 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1c320 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1c330 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1c340 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1c350 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1c360 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1c370 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1c380 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1c390 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1c3a0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1c3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1c3c0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1c3d0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1c3e0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1c3f0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1c400 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1c410 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1c420 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1c430 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1c440 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1c450 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1c460 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1c470 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1c480 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1c490 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1c4a0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1c4b0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1c4c0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1c4d0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1c4e0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1c4f0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1c500 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1c510 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1c520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1c530 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1c540 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1c550 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1c560 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1c570 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1c580 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1c590 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1c5a0 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1c5b0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1c5c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1c5d0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1c5e0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1c5f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1c600 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1c610 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1c620 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1c630 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1c640 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1c650 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1c660 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1c670 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1c680 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1c690 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1c6a0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1c6b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1c6c0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1c6d0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1c6e0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1c6f0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1c700 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1c710 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c720 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1c730 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c740 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1c750 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1c760 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1c770 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1c780 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1c790 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1c7a0 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1c7b0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1c7c0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1c7d0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1c7e0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1c7f0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1c800 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1c810 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c820 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1c830 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1c840 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1c850 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1c860 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1c870 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1c880 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1c890 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1c8a0 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1c8b0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1c8c0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1c8d0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1c8e0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1c8f0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1c900 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1c910 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1c920 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1c930 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1c940 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1c950 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1c960 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1c970 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1c980 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c990 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1c9a0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1c9b0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1c9c0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1c9d0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1c9e0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1c9f0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1ca00 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1ca10 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1ca20 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1ca30 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1ca40 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1ca50 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1ca60 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1ca70 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1ca80 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1ca90 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1caa0 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1cab0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1cac0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1cad0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1cae0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1caf0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1cb00 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1cb10 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1cb20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1cb30 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1cb40 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1cb50 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1cb60 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1cb70 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1cb80 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1cb90 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
1cba0 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  o:.** <ul>.** <l
1cbb0 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  i> the [sqlite3_
1cbc0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1cbd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c   interface.** <l
1cbe0 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68  i> the [count_ch
1cbf0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a  anges pragma].**
1cc00 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67   <li> the [chang
1cc10 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1cc20 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  n].** <li> the [
1cc30 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61  data_version pra
1cc40 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  gma].** </ul>.*/
1cc50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
1cc60 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1cc70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cc80 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1cc90 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1cca0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1ccb0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1ccc0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1ccd0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1cce0 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1ccf0 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1cd00 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1cd10 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1cd20 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1cd30 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1cd40 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1cd50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cd60 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1cd70 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1cd80 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1cd90 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1cda0 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1cdb0 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1cdc0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1cdd0 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1cde0 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1cdf0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1ce00 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1ce10 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1ce20 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1ce30 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1ce40 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1ce50 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1ce60 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1ce70 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1ce80 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1ce90 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1cea0 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1ceb0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1cec0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1ced0 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1cee0 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1cef0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1cf00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 74 68  d..**.** This th
1cf10 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1cf20 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74  _changes(D)] int
1cf30 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1cf40 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rts the number.*
1cf50 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63  * of rows that c
1cf60 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51  hanged due to SQ
1cf70 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  L statement run 
1cf80 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65  against database
1cf90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
1cfa0 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62  .  Any changes b
1cfb0 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  y other database
1cfc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65   connections are
1cfd0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20   ignored..** To 
1cfe0 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61  detect changes a
1cff0 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73  gainst a databas
1d000 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65  e file from othe
1d010 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
1d020 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68  nnections use th
1d030 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76  e [PRAGMA data_v
1d040 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20  ersion] command 
1d050 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  or the.** [SQLIT
1d060 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52  E_FCNTL_DATA_VER
1d070 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74  SION] [file cont
1d080 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rol]..** .** If 
1d090 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1d0a0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1d0b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1d0c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d0d0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1d0e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1d0f0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1d100 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1d110 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1d120 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1d130 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a  t meaningful..**
1d140 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a  .** See also:.**
1d150 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68   <ul>.** <li> th
1d160 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1d170 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  es()] interface.
1d180 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75  ** <li> the [cou
1d190 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1d1a0 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1d1b0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1d1c0 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20  nction].** <li> 
1d1d0 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f  the [data_versio
1d1e0 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  n pragma].** <li
1d1f0 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  > the [SQLITE_FC
1d200 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
1d210 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d  ] [file control]
1d220 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
1d230 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1d240 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1d250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d260 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1d270 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1d280 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1d290 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1d2a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1d2b0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1d2c0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1d2d0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1d2e0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1d2f0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1d300 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1d310 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1d320 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1d330 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1d340 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1d350 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1d360 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1d370 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1d380 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1d390 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1d3a0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1d3b0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1d3c0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1d3d0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1d3e0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1d3f0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1d400 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1d410 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1d420 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1d430 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1d440 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1d450 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1d460 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1d470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1d480 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1d490 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1d4a0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1d4b0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1d4c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1d4d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1d4e0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1d4f0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1d500 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1d510 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1d520 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1d530 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1d540 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1d550 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1d560 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1d570 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1d580 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1d590 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1d5a0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1d5b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1d5c0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1d5d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1d5e0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1d5f0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1d600 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1d610 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1d620 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1d630 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1d640 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1d650 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1d660 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1d670 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1d680 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1d690 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d6a0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1d6b0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1d6c0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1d6d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d6e0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1d6f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1d700 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1d710 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1d720 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1d730 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1d740 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d750 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1d760 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1d770 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1d780 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1d790 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1d7a0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1d7b0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1d7c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1d7d0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1d7e0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1d7f0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1d800 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1d810 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1d820 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1d830 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1d840 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1d850 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1d860 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1d870 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1d880 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1d890 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1d8a0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1d8b0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1d8c0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1d8d0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1d8e0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1d8f0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1d900 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1d910 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d920 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1d930 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1d940 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1d950 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d960 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1d970 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1d980 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1d990 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1d9a0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1d9b0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1d9c0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1d9d0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1d9e0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1d9f0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1da00 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1da10 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1da20 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1da30 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1da40 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1da50 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1da60 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1da70 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1da80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1da90 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1daa0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1dab0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1dac0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1dad0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1dae0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1daf0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1db00 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1db10 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1db20 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1db30 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1db40 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1db50 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1db60 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1db70 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1db80 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1db90 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1dba0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1dbb0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1dbc0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1dbd0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1dbe0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1dbf0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1dc00 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1dc10 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1dc20 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1dc30 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1dc40 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1dc50 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1dc60 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1dc70 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1dc80 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1dc90 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1dca0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1dcb0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1dcc0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1dcd0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1dce0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1dcf0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1dd00 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1dd10 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1dd20 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1dd30 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1dd40 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1dd50 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1dd60 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1dd70 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1dd80 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1dd90 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1dda0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1ddb0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1ddc0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1ddd0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1dde0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ddf0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1de00 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1de10 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1de20 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1de30 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1de40 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1de50 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1de60 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1de70 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1de80 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1de90 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1dea0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1deb0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1dec0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1ded0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1dee0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1def0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1df00 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1df10 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1df20 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1df30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1df40 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1df50 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1df60 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1df70 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1df80 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1df90 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1dfa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dfb0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1dfc0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1dfd0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1dfe0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1dff0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1e000 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1e010 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1e020 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1e030 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1e040 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1e050 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1e060 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1e070 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e080 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e090 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1e0a0 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1e0b0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1e0c0 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1e0d0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1e0e0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1e0f0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1e100 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1e110 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1e120 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1e130 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1e140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e150 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1e160 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1e170 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1e180 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1e190 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1e1a0 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1e1b0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1e1c0 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1e1d0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1e1e0 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1e1f0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1e200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1e210 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1e220 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1e230 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1e240 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1e250 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1e260 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1e270 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1e280 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1e290 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1e2a0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1e2b0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1e2c0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1e2d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1e2e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1e2f0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1e300 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1e310 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1e320 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1e330 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e340 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1e350 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1e360 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1e370 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1e380 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1e390 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1e3a0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1e3b0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1e3c0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1e3d0 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1e3e0 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1e3f0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1e400 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1e410 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1e420 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1e430 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1e440 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1e450 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1e460 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1e470 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1e480 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1e490 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1e4a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1e4b0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1e4c0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1e4d0 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1e4e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1e4f0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1e500 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1e510 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1e520 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1e530 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1e540 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1e550 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1e560 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1e570 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1e580 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1e590 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1e5a0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1e5b0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1e5c0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1e5d0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1e5e0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1e5f0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1e600 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1e610 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1e620 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1e630 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1e640 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1e650 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1e660 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1e670 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1e680 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1e690 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1e6a0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1e6b0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1e6c0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1e6d0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1e6e0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1e6f0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1e700 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1e710 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1e720 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1e730 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1e740 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1e750 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1e760 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1e770 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1e780 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1e790 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1e7a0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1e7b0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1e7c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1e7d0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1e7e0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1e7f0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1e800 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1e810 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1e820 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1e830 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1e840 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1e850 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1e860 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1e870 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1e880 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1e890 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1e8a0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1e8b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1e8c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1e8d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1e8e0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1e8f0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1e900 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1e910 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1e920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1e930 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1e940 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1e950 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1e960 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1e970 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1e980 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1e990 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1e9a0 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1e9b0 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1e9c0 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1e9d0 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1e9e0 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1e9f0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1ea00 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1ea10 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1ea20 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1ea30 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1ea40 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1ea50 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1ea60 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ea70 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ea80 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1ea90 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1eaa0 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1eab0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1eac0 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1ead0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1eae0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1eaf0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1eb00 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1eb10 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1eb20 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1eb30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1eb40 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1eb50 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1eb60 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1eb70 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1eb80 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1eb90 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1eba0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1ebb0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ebc0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1ebd0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1ebe0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1ebf0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1ec00 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1ec10 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1ec20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1ec30 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1ec40 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1ec50 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1ec60 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1ec70 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1ec80 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1ec90 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1eca0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1ecb0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1ecc0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1ecd0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1ece0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1ecf0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1ed00 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1ed10 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1ed20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1ed30 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1ed40 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1ed50 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1ed60 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1ed70 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1ed80 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1ed90 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1eda0 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1edb0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1edc0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1edd0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ede0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1edf0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1ee00 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1ee10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ee20 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1ee30 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1ee40 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1ee50 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1ee60 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1ee70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ee80 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1ee90 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1eea0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1eeb0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1eec0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1eed0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1eee0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1eef0 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1ef00 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1ef10 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1ef20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ef30 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1ef40 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1ef50 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1ef60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ef70 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1ef80 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1ef90 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1efa0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1efb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1efc0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1efd0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1efe0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1eff0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1f000 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1f010 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1f020 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1f030 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1f040 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1f050 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1f060 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1f070 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1f080 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1f090 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1f0a0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1f0b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1f0c0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1f0d0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1f0e0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1f0f0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1f100 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1f110 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1f120 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1f130 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1f140 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1f150 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1f160 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1f170 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1f180 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1f190 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1f1a0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1f1b0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1f1c0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1f1d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1f1e0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1f1f0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1f200 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1f210 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1f220 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1f230 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1f240 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1f250 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1f260 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1f270 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1f280 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1f290 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1f2a0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1f2b0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1f2c0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1f2d0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1f2e0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1f2f0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1f300 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1f310 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1f320 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1f330 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1f340 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1f350 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1f360 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1f370 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1f380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1f390 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1f3a0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1f3b0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1f3c0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1f3d0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1f3e0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1f3f0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1f400 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1f410 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1f420 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1f430 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1f440 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1f450 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1f460 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1f470 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1f480 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f490 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1f4a0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1f4b0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1f4c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1f4d0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1f4e0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1f4f0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1f500 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1f510 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1f520 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f530 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1f540 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1f550 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1f560 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1f570 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1f580 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1f590 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1f5a0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1f5b0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1f5c0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1f5d0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1f5e0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1f5f0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1f600 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f610 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1f620 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1f630 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1f640 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f650 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1f660 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f670 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1f680 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f690 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1f6a0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1f6b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1f6c0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1f6d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1f6e0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1f6f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f700 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1f710 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f720 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1f730 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f740 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1f750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1f760 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1f770 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1f780 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1f790 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1f7a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1f7b0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1f7c0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1f7d0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1f7e0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1f7f0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1f800 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1f810 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1f820 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1f830 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1f840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1f850 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1f860 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1f870 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1f880 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1f890 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1f8a0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1f8b0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1f8c0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1f8d0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1f8e0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1f8f0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1f900 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1f910 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f920 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1f930 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1f940 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1f950 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1f960 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1f970 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1f980 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1f990 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1f9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1f9b0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1f9c0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1f9d0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1f9e0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1f9f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1fa00 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1fa10 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1fa20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1fa30 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1fa40 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1fa50 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1fa60 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1fa70 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1fa80 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1fa90 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1faa0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1fab0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1fac0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1fad0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1fae0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1faf0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1fb00 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1fb10 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1fb20 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1fb30 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1fb40 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1fb50 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1fb60 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1fb70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1fb80 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1fb90 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1fba0 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1fbb0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1fbc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1fbd0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1fbe0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1fbf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1fc00 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1fc10 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1fc20 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1fc30 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1fc40 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1fc50 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1fc60 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1fc70 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1fc80 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1fc90 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1fca0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1fcb0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1fcc0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1fcd0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1fce0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1fcf0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1fd00 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1fd10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1fd20 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1fd30 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1fd40 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1fd50 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1fd60 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1fd70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1fd80 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1fd90 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1fda0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1fdb0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1fdc0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1fdd0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1fde0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1fdf0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1fe00 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74  e common formatt
1fe10 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1fe20 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1fe30 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66 28   library printf(
1fe40 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  ) .** plus some 
1fe50 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1fe60 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 20  tandard formats 
1fe70 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77  ([%q], [%Q], [%w
1fe80 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a  ], and [%z])..**
1fe90 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74 2d   See the [built-
1fea0 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f 63  in printf()] doc
1feb0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 64  umentation for d
1fec0 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  etails..**.** ^T
1fed0 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1fee0 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1fef0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1ff00 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1ff10 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1ff20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1ff30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1ff40 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20 54  alloc64()]..** T
1ff50 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1ff60 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1ff70 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1ff80 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1ff90 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1ffa0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1ffb0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1ffc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1ffd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ffe0 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  64()] is unable 
1fff0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
20000 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
20010 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
20020 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
20030 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
20040 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
20050 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
20060 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
20070 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
20080 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
20090 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
200a0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
200b0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
200c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
200d0 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
200e0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
200f0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
20100 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
20110 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
20120 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
20130 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
20140 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
20150 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
20160 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
20170 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
20180 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
20190 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
201a0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
201b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
201c0 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
201d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
201e0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
201f0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
20200 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
20210 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
20220 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
20230 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
20240 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
20250 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
20260 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
20270 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
20280 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
20290 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
202a0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
202b0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
202c0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
202d0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
202e0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
202f0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
20300 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
20310 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
20320 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
20330 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
20340 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
20350 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
20360 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
20370 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
20380 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
20390 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
203a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
203b0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
203c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
203d0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
203e0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
203f0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
20400 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
20410 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
20420 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
20430 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
20440 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
20450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20460 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
20470 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
20480 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
20490 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
204a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
204b0 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  :  [built-in pri
204c0 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66 28  ntf()], [printf(
204d0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
204e0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
204f0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
20500 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
20510 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
20520 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
20530 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
20540 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20550 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
20560 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
20570 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
20580 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
20590 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
205a0 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
205b0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
205c0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
205d0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
205e0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
205f0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
20600 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
20610 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
20620 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
20630 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
20640 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
20650 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
20660 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
20670 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
20680 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
20690 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
206a0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
206b0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
206c0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
206d0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
206e0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
206f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20700 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20710 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
20720 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
20730 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
20740 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
20750 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
20760 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
20770 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20780 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
20790 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
207a0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
207b0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
207c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
207d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
207e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
207f0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
20800 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
20810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20820 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
20830 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20850 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
20860 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
20870 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
20880 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
20890 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
208a0 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
208b0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
208c0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
208d0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
208e0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
208f0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
20900 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
20910 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
20920 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
20930 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
20940 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
20950 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
20960 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
20970 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
20980 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
20990 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
209a0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
209b0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
209c0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
209d0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
209e0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
209f0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
20a00 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
20a10 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
20a20 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
20a30 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
20a40 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
20a50 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
20a60 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
20a70 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
20a80 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
20a90 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
20aa0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
20ab0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
20ac0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
20ad0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
20ae0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
20af0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
20b00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
20b10 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
20b20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
20b30 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
20b40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20b50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20b60 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
20b70 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
20b80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20b90 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
20ba0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
20bb0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
20bc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20bd0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
20be0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
20bf0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
20c00 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
20c10 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
20c20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
20c30 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
20c40 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
20c50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
20c60 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
20c70 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
20c80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20c90 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
20ca0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
20cb0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
20cc0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
20cd0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
20ce0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
20cf0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
20d00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20d10 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
20d20 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
20d30 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
20d40 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
20d50 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
20d60 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
20d70 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
20d80 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
20d90 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
20da0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20db0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
20dc0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
20dd0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20de0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
20df0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
20e00 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
20e10 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
20e20 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
20e30 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
20e40 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
20e50 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
20e60 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
20e70 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
20e80 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
20e90 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
20ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
20eb0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20ec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20ed0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
20ee0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
20ef0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
20f00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20f10 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
20f20 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
20f30 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
20f40 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
20f50 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20f60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
20f70 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
20f80 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
20f90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20fa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20fb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20fc0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
20fd0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
20fe0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20ff0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
21000 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
21010 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
21020 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
21030 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
21040 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
21050 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
21060 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
21070 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
21080 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
21090 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
210a0 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
210b0 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
210c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
210d0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
210e0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
210f0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
21100 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
21110 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
21120 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
21130 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
21140 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
21150 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
21160 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
21170 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
21180 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
21190 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
211a0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
211b0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
211c0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
211d0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
211e0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
211f0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
21200 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21210 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
21220 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
21230 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
21240 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21250 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
21260 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
21270 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
21280 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
21290 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
212a0 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
212b0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
212c0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
212d0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
212e0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
212f0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
21300 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
21310 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
21320 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
21330 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
21340 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
21350 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
21360 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
21370 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
21380 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
21390 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
213a0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
213b0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
213c0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
213d0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
213e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
213f0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
21400 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
21410 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
21420 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
21430 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
21440 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
21450 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
21460 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
21470 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
21480 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
21490 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
214a0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
214b0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
214c0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
214d0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
214e0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
214f0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
21500 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
21510 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
21520 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
21530 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
21540 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
21550 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
21560 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
21570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
21580 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
21590 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
215a0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
215b0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
215c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
215d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
215e0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
215f0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
21600 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
21610 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
21620 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
21630 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
21640 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
21650 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
21660 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
21670 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
21680 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
21690 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
216a0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
216b0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
216c0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
216d0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
216e0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
216f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
21700 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
21710 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
21720 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
21730 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
21740 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
21750 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
21760 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
21770 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
21780 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
21790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
217a0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
217b0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
217c0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
217d0 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
217e0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
217f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
21800 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
21810 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
21820 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
21830 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
21840 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
21850 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
21860 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
21870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
21880 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
21890 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
218a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
218b0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
218c0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
218d0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
218e0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
218f0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
21900 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
21910 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
21920 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
21930 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
21940 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
21950 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
21960 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
21970 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
21980 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
21990 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
219a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
219b0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
219c0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
219d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
219e0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
219f0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
21a00 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
21a10 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
21a20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
21a30 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
21a40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
21a50 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21a60 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
21a70 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
21a80 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
21a90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
21ab0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
21ac0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
21ad0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
21ae0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
21af0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
21b00 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
21b10 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
21b20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
21b30 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
21b40 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
21b50 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
21b60 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
21b70 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21b80 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
21b90 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
21ba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
21bb0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21bc0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
21bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
21be0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
21bf0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
21c00 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
21c10 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
21c20 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
21c30 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
21c40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
21c50 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
21c60 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
21c70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21c80 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
21c90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21ca0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
21cb0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
21cc0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
21cd0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
21ce0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
21cf0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
21d00 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
21d10 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
21d20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
21d30 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
21d40 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
21d50 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
21d60 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
21d70 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
21d80 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
21d90 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
21da0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
21db0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
21dc0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
21dd0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
21de0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
21df0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
21e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
21e10 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
21e20 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
21e30 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
21e40 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
21e50 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
21e60 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
21e70 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
21e80 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
21e90 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
21ea0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21eb0 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
21ec0 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
21ed0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
21ee0 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
21ef0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
21f00 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
21f10 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
21f20 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
21f30 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
21f40 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
21f50 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
21f60 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
21f70 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
21f80 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
21f90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21fa0 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
21fb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
21fc0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
21fd0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
21fe0 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
21ff0 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
22000 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
22010 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
22020 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
22030 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
22040 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
22050 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
22060 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
22070 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
22080 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
22090 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
220a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
220b0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
220c0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
220d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
220e0 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ite3.** KEYWORDS
220f0 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  : {authorizer ca
22100 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54  llback}.**.** ^T
22110 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
22120 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
22130 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
22140 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
22150 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
22160 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
22170 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
22180 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
22190 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
221a0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
221b0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
221c0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
221d0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
221e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
221f0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
22200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22210 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
22220 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
22230 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
22240 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  re16()], [sqlite
22250 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22260 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
22270 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
22280 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
22290 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
222a0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
222b0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
222c0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
222d0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
222e0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
222f0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
22300 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
22310 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
22320 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
22330 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
22340 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
22350 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
22360 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
22370 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
22380 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
22390 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
223a0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
223b0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
223c0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
223d0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
223e0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
223f0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
22400 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
22410 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
22420 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
22430 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
22440 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
22450 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
22460 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22470 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
22480 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22490 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
224a0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
224b0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
224c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
224d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
224e0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
224f0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
22500 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22510 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
22520 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
22530 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
22540 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
22550 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
22560 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
22570 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
22580 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
22590 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
225a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
225b0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
225c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
225d0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
225e0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
225f0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
22600 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
22610 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
22620 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
22630 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
22640 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
22650 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
22660 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22670 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22680 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
22690 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
226a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
226b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
226c0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
226d0 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
226e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
226f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
22700 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
22710 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
22720 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
22730 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
22740 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
22750 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
22760 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
22770 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
22780 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
22790 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65  llback are eithe
227a0 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
227b0 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  or zero-terminat
227c0 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68  ed strings.** th
227d0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
227e0 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
227f0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
22800 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
22810 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
22820 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
22830 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f  prepared to enco
22840 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  unter a NULL poi
22850 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f  nter in any.** o
22860 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f  f the third thro
22870 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61  ugh the sixth pa
22880 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22890 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
228a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49  llback..**.** ^I
228b0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
228c0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
228d0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
228e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
228f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
22900 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
22910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22920 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
22930 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
22940 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
22950 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
22960 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
22970 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
22980 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
22990 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
229a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
229b0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
229c0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
229d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
229e0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
229f0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
22a00 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
22a10 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
22a20 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74  le..** ^When a t
22a30 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63  able is referenc
22a40 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d  ed by a [SELECT]
22a50 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76   but no column v
22a60 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74  alues are.** ext
22a70 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74  racted from that
22a80 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d   table (for exam
22a90 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c  ple in a query l
22aa0 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63  ike.** "SELECT c
22ab0 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62  ount(*) FROM tab
22ac0 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c  ") then the [SQL
22ad0 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72  ITE_READ] author
22ae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
22af0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
22b00 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20   for that table 
22b10 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61  with a column na
22b20 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d  me that is an em
22b30 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  pty string..** ^
22b40 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
22b50 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
22b60 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
22b70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
22b80 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
22b90 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
22ba0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
22bb0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
22bc0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
22bd0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
22be0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
22bf0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
22c00 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
22c10 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
22c20 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
22c30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
22c40 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
22c50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
22c60 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
22c70 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
22c80 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
22c90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
22ca0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
22cb0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
22cc0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
22cd0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
22ce0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
22cf0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
22d00 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
22d10 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
22d20 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
22d30 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
22d40 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
22d50 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
22d60 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
22d70 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
22d80 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
22d90 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
22da0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
22db0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
22dc0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
22dd0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
22de0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
22df0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22e00 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
22e10 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
22e20 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
22e30 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
22e40 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
22e50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22e60 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
22e70 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
22e80 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
22e90 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
22ea0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
22eb0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
22ec0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
22ed0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
22ee0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
22ef0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
22f00 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
22f10 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
22f20 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22f30 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
22f40 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
22f50 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
22f60 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
22f70 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
22f80 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
22f90 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
22fa0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
22fb0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
22fc0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
22fd0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
22fe0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
22ff0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
23000 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
23010 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
23020 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
23030 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
23040 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
23050 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
23060 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
23070 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
23080 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
23090 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
230a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
230b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
230c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
230d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
230e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
230f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
23100 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
23110 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23120 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
23130 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23140 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
23150 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
23160 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
23170 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23180 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
23190 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
231a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
231b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
231c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
231d0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
231e0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
231f0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
23200 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
23210 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
23220 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
23230 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
23240 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
23250 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
23260 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
23270 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
23280 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
23290 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
232a0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
232b0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
232c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
232d0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
232e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
232f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23300 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
23310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23320 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
23330 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
23340 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
23350 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
23360 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
23370 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
23380 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
23390 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
233a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
233b0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
233c0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
233d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
233e0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
233f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
23400 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
23410 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
23420 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23430 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
23440 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
23450 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
23460 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23470 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
23480 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
23490 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
234a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
234b0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
234c0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
234d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
234e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
234f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23500 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
23510 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
23520 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
23530 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
23540 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
23550 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
23560 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
23570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
23580 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23590 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
235a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
235b0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
235c0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
235d0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
235e0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
235f0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
23600 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
23610 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
23620 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
23630 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
23640 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
23650 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
23660 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
23670 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
23680 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
23690 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
236a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
236b0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
236c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
236d0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
236e0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
236f0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
23700 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
23710 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
23720 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
23730 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
23740 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
23750 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
23760 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
23770 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
23780 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
23790 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
237a0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
237b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
237c0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
237d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
237e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
237f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
23800 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
23810 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
23820 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
23830 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
23840 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
23850 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
23860 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
23870 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
23880 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
23890 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
238a0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
238b0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
238c0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
238d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
238e0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
238f0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
23900 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
23910 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
23920 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
23930 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
23940 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
23950 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
23960 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
23970 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
23980 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
23990 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
239a0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
239b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
239c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
239d0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
239e0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
239f0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
23a00 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
23a10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
23a20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
23a30 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
23a40 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
23a50 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
23a60 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
23a70 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
23a80 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
23a90 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
23aa0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
23ab0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
23ac0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
23ad0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
23ae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23af0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23b00 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
23b10 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
23b20 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
23b30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
23b40 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
23b50 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
23b60 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23b70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23b80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
23b90 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
23ba0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23bb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23bc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23bd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
23be0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
23bf0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23c00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23c20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
23c30 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
23c40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23c50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23c70 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23c80 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
23c90 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23ca0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23cc0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
23cd0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
23ce0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
23cf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23d10 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
23d20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
23d30 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
23d40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23d60 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
23d70 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
23d80 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23d90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23db0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
23dc0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
23dd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23de0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23e00 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
23e10 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
23e20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
23e30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23e50 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
23e60 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
23e70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23e80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23ea0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
23eb0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
23ec0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23ed0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23ef0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
23f00 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
23f10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23f20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23f30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23f40 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
23f50 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
23f60 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
23f70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23f80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23f90 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
23fa0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23fb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23fc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23fd0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
23fe0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
23ff0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
24000 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
24010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24020 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
24030 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
24040 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
24050 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24070 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
24080 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
24090 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
240a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
240b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
240c0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
240d0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
240e0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
240f0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
24100 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
24110 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
24120 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
24130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24140 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
24150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24160 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
24170 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
24180 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24190 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
241a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
241b0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
241c0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
241d0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
241e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
241f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24200 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
24210 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
24220 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
24230 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
24240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24250 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
24260 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
24270 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
24280 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
242a0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
242b0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
242c0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
242d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
242e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
242f0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
24300 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
24310 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
24320 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
24330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
24340 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
24350 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
24360 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
24370 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24380 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
24390 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
243a0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
243b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
243c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
243d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
243e0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
243f0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
24400 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
24410 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
24420 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
24430 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
24440 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
24450 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
24460 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24470 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
24480 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
24490 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
244a0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
244b0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
244c0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
244d0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
244e0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
244f0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
24500 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
24510 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
24520 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
24530 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
24540 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
24550 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
24560 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
24570 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
24580 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24590 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
245a0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
245b0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
245c0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
245d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
245e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
245f0 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
24600 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
24610 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
24620 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
24630 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
24640 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
24650 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24660 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
24670 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
24680 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
24690 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
246a0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
246b0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
246c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
246d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
246e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
246f0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
24700 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
24710 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
24720 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
24730 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
24740 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
24750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24760 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
24770 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24780 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24790 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
247a0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
247b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
247c0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
247d0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
247e0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
247f0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
24800 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
24810 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
24820 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
24830 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
24840 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
24850 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
24860 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
24870 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
24880 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
24890 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
248a0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
248b0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
248c0 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
248d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
248e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
248f0 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
24900 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
24910 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
24920 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
24930 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
24940 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
24950 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
24960 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
24970 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
24980 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
24990 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
249a0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
249b0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
249c0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
249d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
249e0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
249f0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
24a00 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
24a10 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
24a20 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
24a30 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
24a40 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
24a50 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
24a60 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
24a70 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
24a80 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
24a90 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
24aa0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
24ab0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
24ac0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
24ad0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
24ae0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
24af0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
24b00 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
24b10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
24b20 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
24b30 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
24b40 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
24b50 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
24b60 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  k.  Invoking.** 
24b70 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
24b80 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71 6c  trace()] or [sql
24b90 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
24ba0 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68 65   will cancel the
24bb0 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  .** profile call
24bc0 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  back..*/.SQLITE_
24bd0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
24be0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
24bf0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
24c00 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
24c10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
24c20 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
24c30 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
24c40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
24c50 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
24c60 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
24c70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
24c80 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
24c90 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
24ca0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
24cb0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
24cc0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
24cd0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
24ce0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
24cf0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
24d00 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
24d10 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
24d20 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
24d30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
24d40 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
24d50 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a  The M argument.*
24d60 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
24d70 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d  ace_v2(D,M,X,P)]
24d80 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
24d90 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
24da0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
24db0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
24dc0 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
24dd0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
24de0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
24df0 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
24e00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
24e10 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
24e20 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
24e30 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
24e40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24e50 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
24e60 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
24e70 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
24e80 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
24e90 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
24ea0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
24eb0 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
24ec0 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
24ed0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
24ee0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
24ef0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
24f00 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
24f10 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
24f20 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
24f30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
24f40 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24f50 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
24f60 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
24f70 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
24f80 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
24f90 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
24fa0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
24fb0 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
24fc0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24fd0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
24fe0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24ff0 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
25000 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
25010 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
25020 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
25030 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
25040 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
25050 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
25060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25070 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
25080 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
25090 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
250a0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
250b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
250c0 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
250d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
250e0 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
250f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25100 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
25110 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
25120 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
25130 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
25140 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
25150 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
25160 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
25170 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
25180 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
25190 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
251a0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
251b0 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
251c0 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
251d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
251e0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
251f0 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
25200 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
25210 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
25220 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
25230 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
25240 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
25250 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
25260 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
25270 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
25280 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
25290 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
252a0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
252b0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
252c0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
252d0 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
252e0 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
252f0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
25300 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
25310 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
25320 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
25330 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
25340 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
25350 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
25360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
25370 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
25380 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
25390 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
253a0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
253b0 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
253c0 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
253d0 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
253e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
253f0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
25400 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
25410 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
25420 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
25430 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
25440 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
25450 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
25460 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
25470 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
25480 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
25490 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
254a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
254b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
254c0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
254d0 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
254e0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
254f0 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
25500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
25510 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
25520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25530 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
25540 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
25550 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
25560 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
25570 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
25580 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
25590 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
255a0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
255b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
255c0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
255d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
255e0 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
255f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25600 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
25610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25620 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
25630 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
25640 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
25650 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
25660 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
25670 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
25680 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25690 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
256a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
256b0 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
256c0 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
256d0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
256e0 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
256f0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
25700 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
25710 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
25720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25730 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
25740 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
25750 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
25760 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
25770 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
25780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25790 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
257a0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
257b0 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
257c0 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
257d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
257e0 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
257f0 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
25800 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
25810 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
25820 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
25830 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
25840 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
25850 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
25860 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
25870 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
25880 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
25890 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
258a0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
258b0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
258c0 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
258d0 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
258e0 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
258f0 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
25900 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25910 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
25920 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25930 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
25940 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
25950 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
25960 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
25970 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
25980 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
25990 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
259a0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
259b0 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
259c0 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
259d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
259e0 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
259f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
25a00 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
25a10 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
25a20 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
25a30 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
25a40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
25a50 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
25a60 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
25a70 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
25a80 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
25a90 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
25aa0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
25ab0 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
25ac0 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
25ad0 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
25ae0 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
25af0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
25b00 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
25b10 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
25b20 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
25b30 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
25b40 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
25b50 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
25b60 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
25b70 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
25b80 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
25b90 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
25ba0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
25bb0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
25bc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25bd0 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
25be0 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
25bf0 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
25c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
25c10 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
25c20 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
25c30 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
25c40 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
25c50 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
25c60 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
25c70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25c80 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
25c90 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
25ca0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
25cb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25cc0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
25cd0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
25ce0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
25cf0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
25d00 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
25d10 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
25d20 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
25d30 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
25d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
25d50 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
25d60 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
25d70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
25d80 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
25d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
25da0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
25db0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
25dc0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
25dd0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
25de0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
25df0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
25e00 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
25e10 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
25e20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
25e30 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
25e40 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25e50 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
25e60 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
25e70 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
25e80 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
25e90 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
25ea0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
25eb0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
25ec0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
25ed0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
25ee0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
25ef0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
25f00 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
25f10 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
25f20 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
25f30 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
25f40 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
25f50 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
25f60 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
25f70 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
25f80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
25f90 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
25fa0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
25fb0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
25fc0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
25fd0 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
25fe0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
25ff0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
26000 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
26010 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
26020 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
26030 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
26040 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
26050 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
26060 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
26070 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
26080 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
26090 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
260a0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
260b0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
260c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
260d0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
260e0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
260f0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
26100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
26110 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
26120 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
26130 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
26140 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
26150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26160 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
26170 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
26180 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
26190 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
261a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
261b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
261c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
261d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
261e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
261f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
26200 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
26210 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
26220 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
26230 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
26240 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
26250 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
26260 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
26270 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
26280 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
26290 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
262a0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
262b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
262c0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
262d0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
262e0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
262f0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
26300 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
26310 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26320 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
26330 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
26340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
26350 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
26360 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
26370 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
26380 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
26390 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
263a0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
263b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
263c0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
263d0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
263e0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
263f0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
26400 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
26410 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
26420 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
26430 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
26440 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
26450 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
26460 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
26470 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
26480 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
26490 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
264a0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
264b0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
264c0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
264d0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
264e0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
264f0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
26500 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
26510 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
26520 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
26530 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
26540 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
26550 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
26560 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
26570 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
26580 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
26590 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
265a0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
265b0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
265c0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
265d0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
265e0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
265f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
26600 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
26610 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
26620 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
26630 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
26640 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
26650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
26660 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26670 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
26680 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
26690 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
266a0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
266b0 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
266c0 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
266d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
266e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
266f0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
26700 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
26710 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
26720 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
26730 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
26740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26750 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
26760 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
26770 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
26780 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
26790 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
267a0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
267b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
267c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
267d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
267e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
267f0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
26800 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
26810 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
26820 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
26830 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
26840 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
26850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26860 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
26870 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
26880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26890 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
268a0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
268b0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
268c0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
268d0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
268e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
268f0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
26900 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
26910 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
26920 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
26930 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
26940 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
26950 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
26960 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
26970 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
26980 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
26990 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
269a0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
269b0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
269c0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
269d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
269e0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
269f0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
26a00 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
26a10 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
26a20 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
26a30 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
26a40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
26a50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
26a60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
26a70 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
26a80 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
26a90 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
26aa0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
26ab0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
26ac0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
26ad0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
26ae0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
26af0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
26b00 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
26b10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
26b20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
26b30 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
26b40 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
26b50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
26b60 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
26b70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
26b80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
26b90 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
26ba0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
26bb0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
26bc0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
26bd0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
26be0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
26bf0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
26c00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
26c10 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
26c20 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
26c30 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
26c40 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
26c50 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26c60 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
26c70 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
26c80 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
26c90 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
26ca0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
26cb0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
26cc0 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
26cd0 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
26ce0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
26cf0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
26d00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
26d10 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
26d20 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
26d30 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
26d40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26d50 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
26d60 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
26d70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
26d80 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
26d90 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
26da0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
26db0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
26dc0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
26dd0 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
26de0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
26df0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
26e00 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
26e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26e20 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
26e30 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
26e40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
26e50 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
26e60 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
26e70 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
26e80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
26e90 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
26ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
26eb0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
26ec0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
26ed0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26ee0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
26ef0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
26f00 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
26f10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
26f20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
26f30 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
26f40 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
26f50 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
26f60 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
26f70 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
26f80 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26f90 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26fa0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26fb0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
26fc0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
26fd0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26fe0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
26ff0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
27000 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
27010 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27020 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
27030 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
27040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
27050 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
27060 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
27070 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
27080 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
27090 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
270a0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
270b0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
270c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
270d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
270e0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
270f0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
27100 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
27110 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27120 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
27130 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
27140 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
27150 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
27160 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
27170 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
27180 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
27190 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
271a0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
271b0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
271c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
271d0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
271e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
271f0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
27200 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
27210 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
27220 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
27230 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
27240 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
27250 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
27260 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
27270 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
27280 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
27290 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
272a0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
272b0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
272c0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
272d0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
272e0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
272f0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
27300 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
27310 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
27320 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
27330 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
27340 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
27350 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
27360 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
27370 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
27380 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
27390 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
273a0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
273b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
273c0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
273d0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
273e0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
273f0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
27400 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
27410 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
27420 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
27430 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
27440 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
27450 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
27460 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
27470 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
27480 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
27490 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
274a0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
274b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
274c0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
274d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
274e0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
274f0 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67  in the third arg
27500 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
27510 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
27520 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
27530 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
27540 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
27550 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
27560 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
27570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
27580 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
27590 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
275a0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
275b0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
275c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
275d0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
275e0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
275f0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
27600 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
27610 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
27620 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
27630 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
27640 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
27650 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
27660 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
27670 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
27680 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
27690 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
276a0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
276b0 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
276c0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
276d0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
276e0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
276f0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
27700 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
27710 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
27720 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
27730 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
27740 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
27750 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
27760 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
27770 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
27780 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
27790 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
277a0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
277b0 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
277c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
277d0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
277e0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
277f0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
27800 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
27810 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
27820 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
27830 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
27840 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
27850 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
27860 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
27870 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
27880 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
27890 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
278a0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
278b0 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
278c0 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
278d0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
278e0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
278f0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
27900 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
27910 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
27920 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
27930 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
27940 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
27950 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
27960 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
27970 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
27980 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
27990 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
279a0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
279b0 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
279c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
279d0 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
279e0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
279f0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
27a00 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
27a10 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
27a20 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
27a30 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
27a40 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
27a50 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
27a60 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
27a70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
27a80 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
27a90 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
27aa0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
27ab0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
27ac0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
27ad0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
27ae0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
27af0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
27b00 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
27b10 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
27b20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
27b30 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
27b40 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
27b50 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
27b60 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
27b70 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
27b80 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
27b90 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
27ba0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
27bb0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
27bc0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
27bd0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
27be0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
27bf0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
27c00 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
27c10 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
27c20 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
27c30 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
27c40 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
27c50 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
27c60 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
27c70 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
27c80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
27c90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27ca0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27cb0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
27cc0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
27cd0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
27ce0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
27cf0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
27d00 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
27d10 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
27d20 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
27d30 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
27d40 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
27d50 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
27d60 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
27d70 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
27d80 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27d90 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
27da0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
27db0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
27dc0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
27dd0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
27de0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
27df0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
27e00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
27e10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27e20 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
27e30 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
27e40 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
27e50 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
27e60 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
27e70 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
27e80 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
27e90 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
27ea0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
27eb0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
27ec0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27ed0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
27ee0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
27ef0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
27f00 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
27f10 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
27f20 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
27f30 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
27f40 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
27f50 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
27f60 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
27f70 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
27f80 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
27f90 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
27fa0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
27fb0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
27fc0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
27fd0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
27fe0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
27ff0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
28000 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
28010 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
28020 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
28030 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
28040 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
28050 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
28060 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28070 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
28080 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
28090 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
280a0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
280b0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
280c0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
280d0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
280e0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
280f0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
28100 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
28110 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
28120 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
28130 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
28140 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
28150 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
28160 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
28170 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
28180 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
28190 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
281a0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
281b0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
281c0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
281d0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
281e0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
281f0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
28200 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
28210 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
28220 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
28230 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
28240 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
28250 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
28260 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
28270 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
28280 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
28290 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
282a0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
282b0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
282c0 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
282d0 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
282e0 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
282f0 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
28300 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
28310 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
28320 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
28330 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
28340 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
28350 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
28360 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
28370 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28380 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
28390 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
283a0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
283b0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
283c0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
283d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
283e0 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
283f0 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
28400 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
28410 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
28420 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
28430 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
28440 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
28450 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
28460 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
28470 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
28480 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
28490 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
284a0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
284b0 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
284c0 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
284d0 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
284e0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
284f0 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
28500 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
28510 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
28520 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
28530 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
28540 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
28550 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
28560 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
28570 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
28580 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
28590 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
285a0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
285b0 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
285c0 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
285d0 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
285e0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
285f0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
28600 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
28610 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
28620 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
28630 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
28640 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
28650 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
28660 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
28670 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
28680 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
28690 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
286a0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
286b0 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
286c0 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
286d0 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
286e0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
286f0 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
28700 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
28710 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
28720 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
28730 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
28740 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
28750 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
28760 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
28770 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
28780 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
28790 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
287a0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
287b0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
287c0 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
287d0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
287e0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
287f0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
28800 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
28810 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
28820 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
28830 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
28840 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
28850 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
28860 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
28870 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
28880 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
28890 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
288a0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
288b0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
288c0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
288d0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
288e0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
288f0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
28900 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
28910 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
28920 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
28930 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28940 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
28950 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
28960 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
28970 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
28980 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
28990 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
289a0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
289b0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
289c0 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
289d0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
289e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
289f0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
28a00 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
28a10 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
28a20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
28a30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
28a40 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28a50 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
28a60 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
28a70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28a80 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
28a90 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
28aa0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
28ab0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
28ac0 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
28ad0 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
28ae0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
28af0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
28b00 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
28b10 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
28b20 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
28b30 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
28b40 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
28b50 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
28b60 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
28b70 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
28b80 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
28b90 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
28ba0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
28bb0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
28bc0 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
28bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
28be0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
28bf0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
28c00 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
28c10 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
28c20 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
28c30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
28c40 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
28c50 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
28c60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
28c70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
28c80 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
28c90 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
28ca0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
28cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
28cc0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28cd0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
28ce0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
28cf0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
28d00 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
28d10 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
28d20 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
28d30 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
28d40 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
28d50 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
28d60 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
28d70 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
28d80 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
28d90 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
28da0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
28db0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
28dc0 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
28dd0 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
28de0 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
28df0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
28e00 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
28e10 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
28e20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
28e30 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
28e40 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
28e50 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
28e60 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
28e70 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
28e80 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
28e90 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
28ea0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
28eb0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
28ec0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
28ed0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
28ee0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
28ef0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28f00 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
28f10 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
28f20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
28f30 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
28f40 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
28f50 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
28f60 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
28f70 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
28f80 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
28f90 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
28fa0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
28fb0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28fc0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
28fd0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
28fe0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
28ff0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
29000 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
29010 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
29020 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
29030 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
29040 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
29050 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
29060 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
29070 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
29080 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
29090 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
290a0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
290b0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
290c0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
290d0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
290e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
290f0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
29100 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
29110 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
29120 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
29130 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
29140 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
29150 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
29160 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
29170 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
29180 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
29190 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
291a0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
291b0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
291c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
291d0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
291e0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
291f0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
29200 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
29210 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
29220 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
29230 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
29240 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
29250 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
29260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
29270 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
29280 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
29290 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
292a0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
292b0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
292c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
292d0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
292e0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
292f0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
29300 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
29310 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
29320 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
29330 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
29340 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
29350 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
29360 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
29370 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
29380 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
29390 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
293a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
293b0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
293c0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
293d0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
293e0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
293f0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
29400 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
29410 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
29420 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
29430 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
29440 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
29450 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
29460 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
29470 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
29480 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
29490 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
294a0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
294b0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
294c0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
294d0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
294e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
294f0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
29500 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
29510 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
29520 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
29530 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
29540 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
29550 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
29560 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
29570 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
29580 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
29590 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
295a0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
295b0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
295c0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
295d0 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
295e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
295f0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
29600 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
29610 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
29620 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
29630 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
29640 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
29650 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
29660 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
29670 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
29680 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
29690 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
296a0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
296b0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
296c0 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
296d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
296e0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
296f0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
29700 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
29710 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
29720 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
29730 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
29740 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
29750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
29760 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
29770 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
29780 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
29790 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
297a0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
297b0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
297c0 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
297d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
297e0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
297f0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
29800 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
29810 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
29820 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
29830 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
29840 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
29850 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
29860 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
29870 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
29880 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
29890 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
298a0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
298b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
298c0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
298d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
298e0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
298f0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
29900 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
29910 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
29920 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
29930 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
29940 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
29950 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
29960 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
29970 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
29980 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
29990 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
299a0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
299b0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
299c0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
299d0 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
299e0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
299f0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
29a00 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
29a10 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
29a20 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
29a30 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
29a40 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
29a50 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
29a60 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
29a70 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
29a80 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
29a90 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
29aa0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
29ab0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
29ac0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
29ad0 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
29ae0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
29af0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
29b00 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
29b10 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
29b20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
29b30 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
29b40 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
29b50 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
29b60 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
29b70 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
29b80 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
29b90 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
29ba0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
29bb0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
29bc0 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
29bd0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
29be0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
29bf0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
29c00 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
29c10 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
29c20 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
29c30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
29c40 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
29c50 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
29c60 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
29c70 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
29c80 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
29c90 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
29ca0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
29cb0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
29cc0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
29cd0 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
29ce0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
29cf0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29d00 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
29d10 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
29d20 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
29d30 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
29d40 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
29d50 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
29d60 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
29d70 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
29d80 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
29d90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
29da0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
29db0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
29dc0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
29dd0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
29de0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
29df0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
29e00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29e10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
29e20 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
29e30 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
29e40 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
29e50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29e60 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
29e70 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
29e80 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
29e90 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
29ea0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
29eb0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
29ec0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
29ed0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
29ee0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e  * API call..** ^
29ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
29f00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
29f10 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
29f20 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
29f30 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
29f40 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
29f50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29f60 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
29f70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29f80 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
29f90 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bled..**.** The 
29fa0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
29fb0 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  by sqlite3_errco
29fc0 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  de() and/or.** s
29fd0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
29fe0 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20  errcode() might 
29ff0 63 68 61 6e 67 65 20 77 69 74 68 20 65 61 63 68  change with each
2a000 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78   API call..** Ex
2a010 63 65 70 74 2c 20 74 68 65 72 65 20 61 72 65 20  cept, there are 
2a020 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  some interfaces 
2a030 74 68 61 74 20 61 72 65 20 67 75 61 72 61 6e 74  that are guarant
2a040 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20  eed to never.** 
2a050 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2a060 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f   of the error co
2a070 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63  de.  The error-c
2a080 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a  ode preserving.*
2a090 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
2a0a0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a0b0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
2a0c0 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  code().** <li> s
2a0d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
2a0e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69  errcode().** <li
2a0f0 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  > sqlite3_errmsg
2a100 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
2a110 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a  e3_errmsg16().**
2a120 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68   </ul>.**.** ^Th
2a130 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
2a140 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
2a150 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
2a160 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
2a170 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
2a180 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2a190 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
2a1a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
2a1b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2a1c0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
2a1d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2a1e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
2a1f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
2a200 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2a210 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
2a220 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
2a230 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
2a240 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
2a250 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
2a260 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
2a270 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
2a280 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
2a290 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
2a2a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
2a2b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
2a2c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2a2d0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
2a2e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a2f0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
2a300 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
2a310 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
2a320 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
2a330 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
2a340 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
2a350 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2a360 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
2a370 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
2a380 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
2a390 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
2a3a0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
2a3b0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
2a3c0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
2a3d0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
2a3e0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
2a3f0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
2a400 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
2a410 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
2a420 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
2a430 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
2a440 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
2a450 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
2a460 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2a470 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
2a480 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
2a490 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
2a4a0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
2a4b0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
2a4c0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
2a4d0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
2a4e0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
2a4f0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
2a500 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
2a510 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
2a520 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
2a530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a540 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
2a550 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
2a560 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
2a570 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
2a580 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
2a590 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
2a5a0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
2a5b0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
2a5c0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
2a5d0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
2a5e0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
2a5f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
2a600 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
2a610 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
2a620 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
2a630 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
2a640 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
2a650 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
2a660 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
2a670 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
2a680 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
2a690 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
2a6a0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
2a6b0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
2a6c0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
2a6d0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
2a6e0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
2a6f0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
2a700 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2a710 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
2a720 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
2a730 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
2a740 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2a750 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
2a760 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
2a770 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2a780 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
2a790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a7a0 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
2a7b0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2a7c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
2a7d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
2a7e0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
2a7f0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
2a800 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
2a810 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
2a820 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
2a830 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
2a840 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
2a850 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
2a860 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
2a870 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
2a880 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
2a890 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
2a8a0 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
2a8b0 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
2a8c0 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
2a8d0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
2a8e0 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
2a8f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a900 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
2a910 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
2a920 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
2a930 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
2a940 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
2a950 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a960 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
2a970 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
2a980 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
2a990 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2a9a0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
2a9b0 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
2a9c0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
2a9d0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
2a9e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2a9f0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
2aa00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2aa10 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
2aa20 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
2aa30 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
2aa40 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2aa50 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
2aa60 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
2aa70 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
2aa80 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
2aa90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2aaa0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2aab0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
2aac0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2aad0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2aae0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2aaf0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
2ab00 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
2ab10 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
2ab20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
2ab30 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
2ab40 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
2ab50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab60 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
2ab70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2ab80 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
2ab90 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
2aba0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
2abb0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
2abc0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
2abd0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
2abe0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
2abf0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
2ac00 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
2ac10 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
2ac20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
2ac30 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
2ac40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ac50 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
2ac60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ac70 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
2ac80 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
2ac90 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
2aca0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
2acb0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
2acc0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
2acd0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
2ace0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
2acf0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
2ad00 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
2ad10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2ad20 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
2ad30 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
2ad40 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
2ad50 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
2ad60 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
2ad70 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
2ad80 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
2ad90 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
2ada0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
2adb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
2adc0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
2add0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
2ade0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2adf0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
2ae00 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
2ae10 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
2ae20 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
2ae30 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
2ae40 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
2ae50 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
2ae60 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
2ae70 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
2ae80 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
2ae90 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
2aea0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
2aeb0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
2aec0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
2aed0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
2aee0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
2aef0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
2af00 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2af10 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2af20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
2af30 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
2af40 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
2af50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2af60 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
2af70 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
2af80 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
2af90 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
2afa0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
2afb0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
2afc0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
2afd0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
2afe0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
2aff0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
2b000 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
2b010 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
2b020 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2b030 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
2b040 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
2b050 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
2b060 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2b070 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
2b080 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
2b090 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
2b0a0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
2b0b0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
2b0c0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
2b0d0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
2b0e0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
2b0f0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
2b100 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
2b110 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
2b120 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
2b130 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
2b140 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
2b150 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
2b160 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
2b170 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
2b180 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2b190 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
2b1a0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
2b1b0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
2b1c0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
2b1d0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
2b1e0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
2b1f0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
2b200 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
2b210 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
2b220 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
2b230 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
2b240 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
2b250 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
2b260 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2b270 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
2b280 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
2b290 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
2b2a0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
2b2b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
2b2c0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
2b2d0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
2b2e0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
2b2f0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
2b300 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
2b310 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
2b320 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
2b330 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
2b340 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
2b350 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2b360 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
2b370 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
2b380 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
2b390 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
2b3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
2b3b0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
2b3c0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
2b3d0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
2b3e0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
2b3f0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
2b400 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
2b410 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
2b420 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
2b430 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
2b440 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
2b450 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
2b460 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
2b470 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
2b480 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
2b490 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
2b4a0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
2b4b0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
2b4c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
2b4d0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
2b4e0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
2b4f0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
2b500 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
2b510 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
2b520 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b530 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
2b540 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b550 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
2b560 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
2b570 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
2b580 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
2b590 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
2b5a0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
2b5b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
2b5c0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
2b5d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b5e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
2b5f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
2b600 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
2b610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b620 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
2b630 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2b640 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
2b650 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b660 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b670 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
2b680 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
2b690 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
2b6a0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
2b6b0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
2b6c0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2b6d0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
2b6e0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
2b6f0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
2b700 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
2b710 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
2b720 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
2b730 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
2b740 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
2b750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b760 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
2b770 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
2b780 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
2b790 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b7a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b7b0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
2b7c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
2b7d0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
2b7e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2b7f0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2b800 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
2b810 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
2b820 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
2b830 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b840 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
2b850 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2b860 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
2b870 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b880 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
2b890 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
2b8a0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
2b8b0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
2b8c0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
2b8d0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73  tatement.  If [s
2b8e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b8f0 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65  2()] or.** the e
2b900 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20  quivalent tries 
2b910 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63  to allocate spac
2b920 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20  e for more than 
2b930 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65  this many opcode
2b940 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65  s.** in a single
2b950 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b960 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e  ent, an SQLITE_N
2b970 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65  OMEM error is re
2b980 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
2b990 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b9a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2b9b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2b9c0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2b9d0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
2b9e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b9f0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
2ba00 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
2ba10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2ba20 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2ba30 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
2ba40 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2ba50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ba60 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2ba70 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
2ba80 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
2ba90 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
2baa0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
2bab0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2bac0 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
2bad0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2bae0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
2baf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2bb00 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2bb10 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
2bb20 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
2bb30 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
2bb40 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
2bb50 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2bb60 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2bb70 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
2bb80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2bb90 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
2bba0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2bbb0 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
2bbc0 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
2bbd0 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
2bbe0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
2bbf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bc00 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2bc10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2bc20 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2bc30 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2bc40 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2bc50 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
2bc60 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
2bc70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2bc80 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2bc90 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
2bca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2bcb0 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
2bcc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2bcd0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
2bce0 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
2bcf0 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
2bd00 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
2bd10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
2bd20 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
2bd30 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2bd40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bd50 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2bd60 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2bd70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2bd80 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
2bd90 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2bda0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2bdb0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
2bdc0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
2bdd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2bde0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
2bdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
2be00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2be10 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2be20 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
2be30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2be40 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
2be50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
2be60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2be70 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2be80 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
2be90 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2bea0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
2beb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bec0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
2bed0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2bee0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
2bef0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2bf00 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2bf10 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
2bf20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
2bf30 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2bf40 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2bf50 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
2bf60 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2bf70 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
2bf80 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
2bf90 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20  PI3REF: Prepare 
2bfa0 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
2bfb0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2bfc0 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73  ne various flags
2bfd0 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73   that can be pas
2bfe0 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65  sed into.** "pre
2bff0 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65  pFlags" paramete
2c000 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  r of the [sqlite
2c010 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2c020 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c030 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2c040 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2c050 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20  * New flags may 
2c060 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2c070 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2c080 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  QLite..**.** <dl
2c090 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  >.** [[SQLITE_PR
2c0a0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2c0b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c0c0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2c0d0 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  NT</dt>.** <dd>T
2c0e0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2c0f0 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61  E_PERSISTENT fla
2c100 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74  g is a hint to t
2c110 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  he query planner
2c120 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65  .** that the pre
2c130 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c140 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64  will be retained
2c150 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65   for a long time
2c160 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79   and.** probably
2c170 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d   reused many tim
2c180 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74  es.)^ ^Without t
2c190 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74  his flag, [sqlit
2c1a0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2c1b0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2c1c0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2c1d0 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65   assume that the
2c1e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c1f0 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20  ent will .** be 
2c200 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f  used just once o
2c210 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20  r at most a few 
2c220 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64  times and then d
2c230 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a  estroyed using.*
2c240 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2c250 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c  ize()] relativel
2c260 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72  y soon. The curr
2c270 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2c280 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68  on acts.** on th
2c290 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64  is hint by avoid
2c2a0 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b  ing the use of [
2c2b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2c2c0 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a  ] so as not to.*
2c2d0 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69  * deplete the li
2c2e0 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c  mited store of l
2c2f0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
2c300 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
2c310 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61   of.** SQLite ma
2c320 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69  y act on this hi
2c330 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a  nt differently..
2c340 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  **.** [[SQLITE_P
2c350 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2c360 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52  ]] <dt>SQLITE_PR
2c370 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c  EPARE_NORMALIZE<
2c380 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c390 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2c3a0 4f 52 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 73  ORMALIZE flag is
2c3b0 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66   a no-op. This f
2c3c0 6c 61 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  lag used.** to b
2c3d0 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 61  e required for a
2c3e0 6e 79 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ny prepared stat
2c3f0 65 6d 65 6e 74 20 74 68 61 74 20 77 61 6e 74 65  ement that wante
2c400 64 20 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20  d to use the.** 
2c410 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69  [sqlite3_normali
2c420 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72  zed_sql()] inter
2c430 66 61 63 65 2e 20 20 48 6f 77 65 76 65 72 2c 20  face.  However, 
2c440 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2c450 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29  normalized_sql()
2c460 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ] interface is n
2c470 6f 77 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20  ow available to 
2c480 61 6c 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  all.** prepared 
2c490 73 74 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 61  statements, rega
2c4a0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2c4b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 73  r or not they us
2c4c0 65 20 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a  e this.** flag..
2c4d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  **.** [[SQLITE_P
2c4e0 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d  REPARE_NO_VTAB]]
2c4f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50   <dt>SQLITE_PREP
2c500 41 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e  ARE_NO_VTAB</dt>
2c510 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2c520 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54  TE_PREPARE_NO_VT
2c530 41 42 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  AB flag causes t
2c540 68 65 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a  he SQL compiler.
2c550 2a 2a 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 20  ** to return an 
2c560 65 72 72 6f 72 20 28 65 72 72 6f 72 20 63 6f 64  error (error cod
2c570 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 20  e SQLITE_ERROR) 
2c580 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2c590 20 75 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72   uses.** any vir
2c5a0 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20  tual tables..** 
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 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2c5d0 50 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20  PERSISTENT      
2c5e0 20 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65          0x01.#de
2c5f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2c600 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20  ARE_NORMALIZE   
2c610 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 32              0x02
2c620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c630 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20  PREPARE_NO_VTAB 
2c640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c650 30 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x04../*.** CAPI
2c660 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2c670 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c680 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2c690 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2c6a0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2c6b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2c6c0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c6d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2c6e0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2c6f0 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2c700 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2c710 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2c720 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2c730 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2c740 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2c750 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2c760 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2c770 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2c780 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2c790 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c7a0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2c7b0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2c7c0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2c7d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c7e0 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2c7f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c800 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2c810 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2c820 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2c830 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c840 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2c850 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2c860 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2c870 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2c880 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2c890 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2c8a0 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2c8b0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2c8c0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2c8d0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2c8e0 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2c8f0 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2c900 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2c910 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2c920 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2c930 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2c940 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2c950 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2c960 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2c970 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2c980 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2c990 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2c9a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2c9b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c9c0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2c9d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c9e0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2c9f0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2ca00 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2ca10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2ca20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2ca30 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2ca40 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2ca50 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2ca60 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2ca70 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2ca80 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2ca90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2caa0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2cab0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2cac0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2cad0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2cae0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2caf0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2cb00 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2cb10 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2cb20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2cb30 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2cb40 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2cb50 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2cb60 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2cb70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cb80 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2cb90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2cba0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2cbb0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2cbc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2cbd0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2cbe0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2cbf0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2cc00 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2cc10 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2cc20 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2cc30 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2cc40 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2cc50 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2cc60 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2cc70 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2cc80 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2cc90 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2cca0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2ccb0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2ccc0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2ccd0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2cce0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2ccf0 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2cd00 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2cd10 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2cd20 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2cd30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2cd40 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2cd50 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2cd60 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2cd70 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2cd80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2cd90 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2cda0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2cdb0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2cdc0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2cdd0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2cde0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2cdf0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2ce00 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2ce10 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2ce20 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2ce30 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2ce40 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2ce50 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2ce60 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2ce70 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2ce80 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2ce90 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2cea0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2ceb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2cec0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2ced0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2cee0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2cef0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2cf00 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2cf10 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2cf20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2cf30 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2cf40 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2cf50 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2cf60 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2cf70 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2cf80 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2cf90 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2cfa0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2cfb0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2cfc0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2cfd0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2cfe0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2cff0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d000 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2d010 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2d020 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2d030 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2d040 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2d050 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2d060 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2d070 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2d080 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2d090 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2d0a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2d0b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2d0c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d0d0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2d0e0 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2d0f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d100 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2d110 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2d120 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2d130 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2d140 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2d150 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2d160 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2d170 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2d180 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d190 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2d1a0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2d1b0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2d1c0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2d1d0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2d1e0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2d1f0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2d200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d210 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2d220 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2d230 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2d240 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2d250 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2d260 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2d270 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2d280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d290 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2d2a0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2d2b0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2d2c0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2d2d0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2d2e0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2d2f0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2d300 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2d310 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2d320 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2d330 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2d340 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2d350 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2d360 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2d370 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2d380 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2d390 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2d3a0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2d3b0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2d3c0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2d3d0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2d3e0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2d3f0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2d400 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2d410 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2d420 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2d430 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2d440 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2d450 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2d460 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2d470 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2d480 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2d490 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2d4a0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2d4b0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2d4c0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2d4d0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2d4e0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2d4f0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2d500 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2d510 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2d520 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2d530 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d540 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2d550 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2d560 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2d570 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2d580 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2d590 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2d5a0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2d5b0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2d5c0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2d5d0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2d5e0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2d5f0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2d600 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2d610 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2d620 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2d630 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2d640 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2d650 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2d660 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2d670 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2d680 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2d690 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2d6a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2d6b0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2d6c0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2d6d0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2d6e0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2d6f0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2d700 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2d710 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2d720 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2d730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2d740 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2d750 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2d760 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2d770 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2d780 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2d790 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2d7a0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2d7b0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2d7c0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2d7d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2d7e0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2d7f0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2d800 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2d810 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d820 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2d830 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2d840 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2d850 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2d860 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2d870 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2d880 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2d890 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </ol>.**.** <p>^
2d8a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d8b0 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2d8c0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2d8d0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2d8e0 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2d8f0 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2d900 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2d910 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2d920 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2d930 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2d940 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2d950 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2d960 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2d970 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2d980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d990 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2d9a0 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2d9b0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2d9c0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2d9d0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2d9e0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2d9f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2da00 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2da10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2da20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2da30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2da40 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2da50 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2da60 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2da70 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2da80 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2da90 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2daa0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2dab0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2dac0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2dad0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2dae0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2daf0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2db00 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2db10 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2db20 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2db30 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2db40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2db50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2db60 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2db70 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2db80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2db90 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2dba0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2dbb0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2dbc0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2dbd0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2dbe0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2dbf0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2dc00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2dc10 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2dc20 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2dc30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2dc40 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2dc50 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2dc60 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2dc70 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2dc80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2dc90 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2dca0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2dcb0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2dcc0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2dcd0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2dce0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2dcf0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2dd00 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2dd10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2dd20 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2dd30 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2dd40 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2dd50 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2dd60 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2dd70 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2dd80 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2dd90 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2dda0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ddb0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ddc0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2ddd0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2dde0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ddf0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2de00 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2de10 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2de20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2de30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2de40 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2de50 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2de60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2de70 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2de80 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2de90 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2dea0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2deb0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2dec0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ded0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2dee0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2def0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2df00 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2df10 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2df20 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2df30 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2df40 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2df50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2df60 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2df70 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2df80 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2df90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2dfa0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2dfb0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2dfc0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2dfd0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2dfe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2dff0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2e000 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2e010 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2e020 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2e030 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2e040 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e050 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2e060 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2e070 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2e080 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2e090 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2e0a0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2e0b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2e0c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2e0d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2e0e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2e0f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2e100 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2e110 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2e120 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2e130 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2e140 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2e150 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2e160 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2e170 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2e180 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2e190 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2e1a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2e1b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2e1c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2e1d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2e1e0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2e1f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2e200 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2e210 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2e220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e230 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2e240 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2e250 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e260 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2e270 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2e280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e290 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2e2a0 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2e2b0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2e2c0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2e2d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e2e0 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2e2f0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2e300 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2e310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e320 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2e330 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e340 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2e350 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2e360 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2e370 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e380 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e390 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e3a0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2e3b0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2e3c0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2e3d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e3e0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2e3f0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2e400 78 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65  xpanded..** ^The
2e410 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69   sqlite3_normali
2e420 7a 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  zed_sql(P) inter
2e430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e440 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2e450 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2e460 61 69 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61  aining the norma
2e470 6c 69 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f  lized SQL text o
2e480 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2e490 6d 65 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20  ment P.  The.** 
2e4a0 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74  semantics used t
2e4b0 6f 20 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51  o normalize a SQ
2e4c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  L statement are 
2e4d0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2e4e0 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68  subject.** to ch
2e4f0 61 6e 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69  ange.  At a mini
2e500 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c  mum, literal val
2e510 75 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c  ues will be repl
2e520 61 63 65 64 20 77 69 74 68 20 73 75 69 74 61 62  aced with suitab
2e530 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  le.** placeholde
2e540 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  rs..**.** ^(For 
2e550 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2e560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e570 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2e580 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2e590 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2e5a0 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2e5b0 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2e5c0 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2e5d0 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2e5e0 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2e5f0 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2e600 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2e610 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2e620 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2e630 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2e640 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2e650 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2e660 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2e670 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2e680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e690 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e6a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e6b0 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2e6c0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2e6d0 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2e6e0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2e6f0 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2e700 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2e710 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2e720 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2e730 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2e740 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2e750 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2e760 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2e770 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2e780 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2e790 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2e7a0 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2e7b0 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2e7c0 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2e7d0 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2e7e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2e7f0 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2e800 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2e810 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2e820 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2e830 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20  ** ^The strings 
2e840 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2e850 74 65 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73  te3_sql(P) and s
2e860 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2e870 64 5f 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20  d_sql(P).** are 
2e880 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2e890 65 20 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61  e and are automa
2e8a0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2e8b0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  en the prepared.
2e8c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
2e8d0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2e8e0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2e8f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2e900 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2e910 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2e920 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2e930 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2e940 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2e950 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2e960 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2e970 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2e980 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2e990 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2e9a0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2e9b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e9c0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2e9d0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2e9e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2e9f0 6d 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  mt);.const char 
2ea00 2a 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69  *sqlite3_normali
2ea10 7a 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  zed_sql(sqlite3_
2ea20 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2ea30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ea40 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
2ea50 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
2ea60 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
2ea70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ea80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ea90 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2eaa0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
2eab0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2eac0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2ead0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
2eae0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2eaf0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
2eb00 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
2eb10 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
2eb20 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2eb30 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2eb40 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
2eb50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2eb60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2eb70 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
2eb80 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
2eb90 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2eba0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
2ebb0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
2ebc0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2ebd0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
2ebe0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
2ebf0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
2ec00 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
2ec10 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
2ec20 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
2ec30 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
2ec40 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
2ec50 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2ec60 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
2ec70 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
2ec80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2ec90 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
2eca0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
2ecb0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
2ecc0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2ecd0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
2ece0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
2ecf0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
2ed00 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2ed10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2ed20 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
2ed30 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2ed40 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
2ed50 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
2ed60 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
2ed70 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
2ed80 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
2ed90 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
2eda0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
2edb0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
2edc0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
2edd0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2ede0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2edf0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
2ee00 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
2ee10 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
2ee20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
2ee30 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2ee40 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
2ee50 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
2ee60 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
2ee70 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
2ee80 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
2ee90 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
2eea0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
2eeb0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
2eec0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
2eed0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2eee0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2eef0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
2ef00 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
2ef10 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
2ef20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
2ef30 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
2ef40 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
2ef50 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
2ef60 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
2ef70 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2ef80 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
2ef90 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  sk..** ^The sqli
2efa0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2efb0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
2efc0 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b  turns true for [
2efd0 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20  BEGIN] since.** 
2efe0 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73  [BEGIN] merely s
2eff0 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61  ets internal fla
2f000 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47  gs, but the [BEG
2f010 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41  IN|BEGIN IMMEDIA
2f020 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49  TE] and.** [BEGI
2f030 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56  N|BEGIN EXCLUSIV
2f040 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74  E] commands do t
2f050 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73  ouch the databas
2f060 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69  e and so.** sqli
2f070 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2f080 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73  y() returns fals
2f090 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d  e for those comm
2f0a0 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ands..*/.int sql
2f0b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f0c0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
2f0d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2f0e0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2f0f0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
2f100 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
2f110 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
2f120 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f130 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2f140 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2f150 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
2f160 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2f170 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
2f180 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f190 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
2f1a0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
2f1b0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
2f1c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2f1d0 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
2f1e0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
2f1f0 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
2f200 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
2f210 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
2f220 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
2f230 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
2f240 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f250 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f260 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
2f270 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f280 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
2f290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2f2a0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
2f2b0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2f2c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
2f2d0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
2f2e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f2f0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
2f300 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2f310 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
2f320 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
2f330 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
2f340 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2f350 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
2f360 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
2f370 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
2f380 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
2f390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f3a0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
2f3b0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
2f3c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2f3d0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
2f3e0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
2f3f0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
2f400 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
2f410 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
2f420 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
2f430 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
2f440 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
2f450 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
2f460 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
2f470 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
2f480 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
2f490 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2f4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
2f4b0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
2f4c0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
2f4d0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
2f4e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f4f0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
2f500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
2f510 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
2f520 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
2f530 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
2f540 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
2f550 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
2f560 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
2f570 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
2f580 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2f590 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
2f5a0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
2f5b0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
2f5c0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
2f5d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
2f5e0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
2f5f0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
2f600 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
2f610 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
2f620 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
2f630 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f640 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
2f650 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
2f660 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
2f670 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
2f680 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
2f690 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f6a0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
2f6b0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
2f6c0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
2f6d0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
2f6e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f6f0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
2f700 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
2f710 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
2f720 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
2f730 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
2f740 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
2f750 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
2f760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f770 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
2f780 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
2f790 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2f7a0 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  e used to constr
2f7b0 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72  uct a new .** pr
2f7c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f7d0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e  value from an un
2f7e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f7f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
2f800 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
2f810 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
2f820 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
2f830 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
2f840 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
2f850 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
2f860 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2f870 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
2f880 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f890 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
2f8a0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2f8b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
2f8c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f8d0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
2f8e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
2f8f0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
2f900 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
2f910 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2f920 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
2f930 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2f940 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
2f950 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
2f960 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
2f970 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
2f980 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
2f990 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2f9a0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
2f9b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2f9c0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
2f9d0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
2f9e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2f9f0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2fa00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2fa10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2fa20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
2fa30 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
2fa40 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
2fa50 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
2fa60 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
2fa70 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
2fa80 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
2fa90 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
2faa0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
2fab0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2fac0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2fad0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2fae0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
2faf0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
2fb00 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
2fb10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fb20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
2fb30 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
2fb40 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
2fb50 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
2fb60 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
2fb70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2fb80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
2fb90 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
2fba0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2fbb0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
2fbc0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2fbd0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2fbe0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
2fbf0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
2fc00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2fc10 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
2fc20 20 62 65 20 75 73 65 64 20 61 73 20 61 72 67 75   be used as argu
2fc30 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ments.** to [sql
2fc40 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2fc50 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62  e()], [sqlite3_b
2fc60 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e  ind_value()], an
2fc70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  d.** [sqlite3_va
2fc80 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54  lue_dup()]..** T
2fc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2fca0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2fcb0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2fcc0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2fcd0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2fce0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fcf0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2fd00 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2fd10 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
2fd20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2fd30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fd40 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2fd50 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2fd60 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2fd70 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2fd80 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2fd90 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2fda0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2fdb0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2fdc0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2fdd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2fde0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2fdf0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2fe00 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2fe10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fe20 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2fe30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fe40 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2fe50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fe60 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2fe70 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2fe80 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2fe90 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2fea0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2feb0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2fec0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2fed0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2fee0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2fef0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2ff00 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ff10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2ff20 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2ff30 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2ff40 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2ff50 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2ff60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2ff70 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2ff80 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2ff90 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2ffa0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2ffb0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2ffc0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2ffd0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2ffe0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2fff0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
30000 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
30010 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
30020 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
30030 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
30040 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
30050 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30060 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
30070 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
30080 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
30090 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
300a0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
300b0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
300c0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
300d0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
300e0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
300f0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
30100 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
30110 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
30120 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
30130 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
30140 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
30150 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
30160 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
30170 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
30180 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
30190 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
301a0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
301b0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
301c0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
301d0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
301e0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
301f0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
30200 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
30210 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
30220 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
30230 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
30240 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
30250 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
30260 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
30270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
30290 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
302a0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
302b0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
302c0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
302d0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
302e0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
302f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30300 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
30310 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
30320 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
30330 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
30340 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
30350 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
30360 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
30370 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
30380 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
30390 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
303a0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
303b0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
303c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
303d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
303e0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
303f0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
30400 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
30410 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
30420 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
30430 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
30440 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
30450 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
30460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30470 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30480 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
30490 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
304a0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
304b0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
304c0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
304d0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
304e0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
304f0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
30500 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
30510 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
30520 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
30530 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
30540 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
30550 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
30560 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
30570 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
30580 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
30590 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
305a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
305b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
305c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
305d0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
305e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
305f0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
30600 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
30610 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
30620 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
30630 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
30640 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
30650 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
30660 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
30670 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
30680 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
30690 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
306a0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
306b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
306c0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
306d0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
306e0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
306f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
30700 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
30710 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
30720 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
30730 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
30740 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
30750 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30760 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
30770 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
30780 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
30790 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
307a0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
307b0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
307c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
307d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
307e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
307f0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
30800 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
30810 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
30820 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
30830 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
30840 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
30850 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
30860 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
30870 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
30880 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
30890 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
308a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
308b0 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
308c0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
308d0 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
308e0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
308f0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
30900 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
30910 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
30920 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
30930 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
30940 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
30950 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
30960 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
30970 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
30980 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
30990 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
309a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
309b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
309c0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
309d0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
309e0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
309f0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
30a00 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
30a10 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
30a20 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
30a30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
30a40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
30a50 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
30a60 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
30a70 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
30a80 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
30a90 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
30aa0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
30ab0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
30ac0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
30ad0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
30ae0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
30af0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
30b00 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
30b10 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
30b20 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
30b30 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
30b40 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
30b50 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
30b60 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
30b70 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
30b80 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
30b90 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
30ba0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
30bb0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
30bc0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
30bd0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
30be0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
30bf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
30c00 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
30c10 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
30c20 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
30c30 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
30c40 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
30c50 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
30c60 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
30c70 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
30c80 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
30c90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
30ca0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
30cb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
30cc0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
30cd0 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
30ce0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
30cf0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
30d00 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
30d10 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
30d20 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
30d30 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
30d40 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
30d50 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
30d60 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
30d70 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
30d80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
30d90 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
30da0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
30db0 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
30dc0 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
30dd0 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
30de0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
30df0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
30e00 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
30e10 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
30e20 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
30e30 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
30e40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
30e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
30e60 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
30e70 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
30e80 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
30e90 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
30ea0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
30eb0 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
30ec0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
30ed0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
30ee0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
30ef0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
30f00 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
30f10 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
30f20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
30f30 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
30f40 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
30f50 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
30f60 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
30f70 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
30f80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
30f90 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
30fa0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
30fb0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
30fc0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
30fd0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
30fe0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
30ff0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
31000 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31010 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53  3_bind_pointer(S
31020 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e  ,I,P,T,D) routin
31030 65 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74  e causes the I-t
31040 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  h parameter in.*
31050 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31060 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65  ement] S to have
31070 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66   an SQL value of
31080 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c   NULL, but to al
31090 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61  so be.** associa
310a0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69  ted with the poi
310b0 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54  nter P of type T
310c0 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65 72 20  .  ^D is either 
310d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
310e0 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  r.** a pointer t
310f0 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
31100 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e  unction for P. ^
31110 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
31120 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75  ke the.** destru
31130 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
31140 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
31150 20 50 20 77 68 65 6e 20 69 74 20 69 73 20 66 69   P when it is fi
31160 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
31170 50 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65  P.  The T parame
31180 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
31190 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70  static string, p
311a0 72 65 66 65 72 61 62 6c 79 20 61 20 73 74 72 69  referably a stri
311b0 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54  ng.** literal. T
311c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
311d0 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e  pointer() routin
311e0 65 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  e is part of the
311f0 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73  .** [pointer pas
31200 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20  sing interface] 
31210 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65  added for SQLite
31220 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e   3.20.0..**.** ^
31230 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
31240 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
31250 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
31260 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
31270 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
31280 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31290 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
312a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
312b0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
312c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
312d0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
312e0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
312f0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
31300 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
31310 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
31320 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
31330 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
31340 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
31350 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
31360 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
31370 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
31380 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
31390 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
313a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
313b0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
313c0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
313d0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
313e0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
313f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
31400 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
31410 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
31420 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
31430 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
31440 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
31450 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31460 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
31470 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
31480 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
31490 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
314a0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
314b0 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
314c0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
314d0 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
314e0 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
314f0 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
31500 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
31510 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
31520 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
31530 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
31540 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
31550 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
31560 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
31570 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
31580 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
31590 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
315a0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
315b0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
315c0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
315d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
315e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
315f0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
31600 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31610 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
31620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31630 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
31640 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
31650 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
31660 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
31670 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
31680 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
31690 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
316a0 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
316b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
316c0 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
316d0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
316e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
316f0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
31700 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
31710 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
31720 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
31730 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
31740 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
31750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31760 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
31770 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
31780 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31790 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
317a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
317b0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
317c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
317d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
317e0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
317f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
31800 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
31810 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
31820 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
31830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31840 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
31850 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
31860 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
31870 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
31880 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31890 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
318a0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
318b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
318c0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
318d0 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
318e0 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
318f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
31900 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
31910 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
31920 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
31930 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
31940 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69  ind_pointer(sqli
31950 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
31960 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
31970 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  r*,void(*)(void*
31980 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
31990 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
319a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
319b0 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71  , int n);.int sq
319c0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
319d0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
319e0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
319f0 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
31a00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31a10 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
31a20 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
31a30 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31a40 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
31a50 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
31a60 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
31a70 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
31a80 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
31a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31aa0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
31ab0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
31ac0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
31ad0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
31ae0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
31af0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
31b00 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
31b10 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
31b20 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
31b30 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
31b40 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
31b50 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
31b60 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
31b70 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
31b80 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
31b90 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
31ba0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
31bb0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
31bc0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
31bd0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
31be0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
31bf0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
31c00 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
31c10 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
31c20 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
31c30 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
31c40 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
31c50 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
31c60 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
31c70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
31c80 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
31c90 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
31ca0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31cb0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
31cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31cd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
31ce0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
31cf0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31d00 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
31d10 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
31d20 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
31d30 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
31d40 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
31d50 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31d60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
31d70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
31d80 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
31d90 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
31da0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
31db0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
31dc0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
31dd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
31de0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
31df0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
31e00 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
31e10 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
31e20 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
31e30 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
31e40 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
31e50 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
31e60 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
31e70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
31e80 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
31e90 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
31ea0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
31eb0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
31ec0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
31ed0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
31ee0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
31ef0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
31f00 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
31f10 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
31f20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
31f30 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
31f40 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
31f50 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
31f60 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
31f70 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
31f80 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
31f90 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
31fa0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
31fb0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
31fc0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
31fd0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
31fe0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
31ff0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
32000 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
32010 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
32020 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
32030 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
32040 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
32050 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
32060 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
32070 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
32080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32090 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  6()],.** [sqlite
320a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
320b0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ], or [sqlite3_p
320c0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
320d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
320e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
320f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
32100 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32110 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
32120 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
32130 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32140 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
32150 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
32160 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
32170 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
32180 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
32190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
321a0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
321b0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
321c0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
321d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
321e0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
321f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
32200 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
32210 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
32220 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
32230 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
32240 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
32250 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
32260 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
32270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32280 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
32290 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
322a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
322b0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
322c0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
322d0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
322e0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
322f0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
32300 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
32310 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
32320 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
32330 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
32340 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
32350 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  re16_v2()] or.**
32360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32370 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v3()]..**.**
32380 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32390 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
323a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
323b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
323c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
323d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
323e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
323f0 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69  er_name()]..*/.i
32400 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32410 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
32420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
32430 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
32440 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32450 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
32460 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
32470 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
32480 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32490 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
324a0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
324b0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
324c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
324d0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
324e0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
324f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
32500 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
32510 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32520 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
32530 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
32540 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
32550 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
32560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
32570 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
32580 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
32590 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
325a0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
325b0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
325c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
325d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
325e0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
325f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
32600 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
32610 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
32620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32630 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
32640 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
32650 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
32660 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
32670 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
32680 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
32690 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
326a0 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
326b0 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
326c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
326d0 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
326e0 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
326f0 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
32700 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
32710 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
32720 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
32730 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
32740 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
32750 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
32760 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
32770 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
32780 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
32790 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
327a0 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
327b0 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
327c0 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
327d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
327e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
327f0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
32800 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32810 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
32820 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
32830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
32840 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
32850 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
32860 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32870 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
32880 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
32890 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
328a0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
328b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
328c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
328d0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
328e0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
328f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
32900 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
32910 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32920 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
32930 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
32940 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
32950 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
32960 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
32970 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
32980 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
32990 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
329a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
329b0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
329c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
329d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
329e0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
329f0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
32a00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
32a10 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
32a20 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
32a30 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
32a40 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
32a50 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
32a60 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
32a70 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
32a80 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
32a90 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
32aa0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
32ab0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32ac0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
32ad0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
32ae0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
32af0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
32b00 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
32b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
32b20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
32b30 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
32b40 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
32b50 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
32b60 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
32b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
32b80 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
32b90 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
32ba0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
32bb0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
32bc0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
32bd0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
32be0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
32bf0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
32c00 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
32c10 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
32c20 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
32c30 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
32c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
32c50 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
32c60 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
32c70 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
32c80 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
32c90 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
32ca0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
32cb0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
32cc0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
32cd0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
32ce0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
32cf0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
32d00 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
32d10 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
32d20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
32d30 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
32d40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
32d50 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
32d60 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
32d70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32d80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
32d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32da0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
32db0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
32dc0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
32dd0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
32de0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
32e00 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
32e10 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
32e20 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
32e30 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
32e40 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
32e50 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
32e60 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
32e70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
32e80 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
32e90 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
32ea0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
32eb0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
32ec0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
32ed0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
32ee0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
32ef0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
32f00 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
32f10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
32f20 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
32f30 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
32f40 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
32f50 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
32f60 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
32f70 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
32f80 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
32f90 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
32fa0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
32fb0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
32fc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32fd0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
32fe0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
32ff0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33000 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
33010 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
33020 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
33030 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
33040 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
33050 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
33060 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
33070 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
33080 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
33090 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
330a0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
330b0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
330c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
330d0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
330e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
330f0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
33100 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
33110 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
33120 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
33130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
33140 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
33150 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
33160 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
33170 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
33180 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
33190 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
331a0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
331b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
331c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
331d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
331e0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
331f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
33200 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
33210 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
33220 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
33230 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
33240 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
33250 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
33260 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
33270 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
33280 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
33290 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
332a0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
332b0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
332c0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
332d0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
332e0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
332f0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
33300 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
33310 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
33320 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
33330 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
33340 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
33350 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
33360 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
33370 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
33380 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
33390 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
333a0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
333b0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
333c0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
333d0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
333e0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
333f0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
33400 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
33410 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
33420 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
33430 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
33440 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
33450 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
33460 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
33470 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
33480 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
33490 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
334a0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
334b0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
334c0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
334d0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
334e0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
334f0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
33500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
33510 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
33520 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
33530 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
33540 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
33550 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
33560 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
33570 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
33580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
33590 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
335a0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
335b0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
335c0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
335d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
335e0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
335f0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
33600 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
33610 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
33620 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
33630 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
33640 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
33650 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
33660 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
33670 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33680 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
33690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
336a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
336b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
336c0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
336d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
336e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
336f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
33700 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
33710 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
33720 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
33730 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
33740 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
33750 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
33760 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33770 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
33780 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
33790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
337a0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
337b0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
337c0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
337d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
337e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
337f0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
33800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33810 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
33820 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
33830 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
33840 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
33850 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
33860 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
33870 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
33880 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
33890 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
338a0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
338b0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
338c0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
338d0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
338e0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
338f0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
33900 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
33910 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
33920 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
33930 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
33940 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
33950 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
33960 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
33970 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
33980 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
33990 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
339a0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
339b0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
339c0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
339d0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
339e0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
339f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
33a00 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
33a10 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
33a20 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
33a30 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
33a40 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
33a50 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
33a60 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
33a70 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
33a80 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
33a90 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
33aa0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
33ab0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
33ac0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
33ad0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
33ae0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
33af0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
33b00 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
33b10 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
33b20 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
33b30 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
33b40 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
33b50 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
33b60 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
33b70 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
33b80 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
33b90 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
33ba0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
33bb0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
33bc0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
33bd0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
33be0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
33bf0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
33c00 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
33c10 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
33c20 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
33c30 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
33c40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
33c50 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
33c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
33c70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
33c80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
33c90 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
33ca0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
33cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
33cc0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
33cd0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
33ce0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33cf0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
33d00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33d10 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
33d20 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f  ared using any o
33d30 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
33d40 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
33d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
33d60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
33d70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
33d80 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
33d90 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72  epare16_v3()] or
33da0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
33db0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
33dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33dd0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
33de0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
33df0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
33e00 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
33e10 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
33e20 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
33e30 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
33e40 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
33e50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
33e60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
33e70 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
33e80 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
33e90 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
33ea0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
33eb0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
33ec0 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  X" interfaces.**
33ed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33ee0 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
33ef0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
33f00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33f10 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73  e16_v3()],.** [s
33f20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33f30 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
33f40 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
33f50 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
33f60 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
33f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33f80 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
33f90 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
33fa0 76 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  vX" interface is
33fb0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
33fc0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
33fd0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
33fe0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
33ff0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
34000 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
34010 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
34020 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
34030 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
34040 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
34050 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
34060 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
34070 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
34080 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
34090 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
340a0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
340b0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
340c0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
340d0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
340e0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
340f0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
34100 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
34110 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
34120 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
34130 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
34140 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
34150 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
34160 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34170 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
34180 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
34190 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
341a0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
341b0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
341c0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
341d0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
341e0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
341f0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
34200 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
34210 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
34220 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
34230 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
34240 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
34250 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
34260 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
34270 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
34280 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
34290 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
342a0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
342b0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
342c0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
342d0 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
342e0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
342f0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
34300 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
34310 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
34320 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
34330 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
34340 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
34350 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
34360 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
34370 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
34380 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
34390 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
343a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
343b0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
343c0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
343d0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
343e0 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
343f0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
34400 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
34410 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
34420 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
34430 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
34440 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
34450 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
34460 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
34470 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
34480 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
34490 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
344a0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
344b0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
344c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
344d0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
344e0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
344f0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
34500 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
34510 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
34520 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
34530 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
34540 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
34550 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
34560 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
34570 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
34580 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
34590 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
345a0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
345b0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
345c0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
345d0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
345e0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
345f0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
34600 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
34610 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
34620 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
34630 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
34640 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
34650 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
34660 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34670 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
34680 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
34690 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
346a0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
346b0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
346c0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
346d0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
346e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
346f0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
34700 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
34710 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
34720 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
34730 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
34740 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
34750 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
34760 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
34770 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34780 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
34790 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
347a0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
347b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
347c0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
347d0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
347e0 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
347f0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
34800 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
34810 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
34820 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
34830 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
34840 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
34850 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
34860 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
34870 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
34880 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
34890 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
348a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
348b0 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
348c0 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
348d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
348e0 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
348f0 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
34900 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
34910 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
34920 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
34930 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
34940 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
34950 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
34960 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
34970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
34980 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
34990 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
349a0 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
349b0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
349c0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
349d0 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  er [version 3.6.
349e0 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33  23.1] ([dateof:3
349f0 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c  .6.23.1],.** sql
34a00 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
34a10 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
34a20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
34a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
34a40 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
34a50 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
34a60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
34a70 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
34a80 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
34a90 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
34aa0 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
34ab0 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
34ac0 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
34ad0 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
34ae0 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
34af0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
34b00 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
34b10 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
34b20 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
34b30 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
34b40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
34b50 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
34b60 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
34b70 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
34b80 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
34b90 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
34ba0 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
34bb0 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
34bc0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
34bd0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
34be0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
34bf0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
34c00 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
34c10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
34c20 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
34c30 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
34c40 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
34c50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34c60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34c70 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
34c80 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
34c90 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
34ca0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
34cb0 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
34cc0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
34cd0 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
34ce0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
34cf0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
34d00 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
34d10 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
34d20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
34d30 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
34d40 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
34d50 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
34d60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
34d70 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73  pare_v3()] or [s
34d80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34d90 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
34da0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
34db0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34dc0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
34dd0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
34de0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
34df0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
34e00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34e10 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
34e20 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
34e30 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
34e40 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
34e50 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
34e60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
34e70 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
34e80 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  of the "vX" inte
34e90 72 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d  rfaces is recomm
34ea0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
34eb0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
34ec0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
34ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
34ee0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
34ef0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
34f00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34f10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
34f20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
34f30 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
34f40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34f50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
34f60 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
34f70 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
34f80 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
34f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
34fa0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
34fb0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
34fc0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
34fd0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
34fe0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
34ff0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
35000 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
35010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
35020 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
35030 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
35040 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
35050 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
35060 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
35070 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
35080 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
35090 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
350a0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
350b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
350c0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
350d0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
350e0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
350f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
35100 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
35110 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
35120 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
35130 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
35140 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
35150 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
35160 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
35170 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
35180 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
35190 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
351a0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
351b0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
351c0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
351d0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
351e0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
351f0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
35200 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
35210 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
35220 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
35230 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
35240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
35250 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
35260 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
35270 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
35280 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
35290 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
352a0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
352b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
352c0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
352d0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
352e0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
352f0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
35300 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
35310 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35320 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
35330 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
35340 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
35350 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
35360 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
35370 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
35380 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
35390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
353a0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
353b0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
353c0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
353d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
353e0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
353f0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
35400 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
35410 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
35420 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
35430 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
35440 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
35450 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
35460 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
35470 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
35480 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
35490 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
354a0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
354b0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
354c0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
354d0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
354e0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
354f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
35500 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
35510 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
35520 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
35530 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
35540 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
35550 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
35560 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
35570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
35580 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
35590 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
355a0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
355b0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
355c0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
355d0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
355e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
355f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e  3_stmt.**.** <b>
35600 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20  Summary:</b>.** 
35610 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62  <blockquote><tab
35620 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c  le border=0 cell
35630 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70  padding=0 cellsp
35640 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e  acing=0>.** <tr>
35650 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
35660 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74  olumn_blob</b><t
35670 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42  d>&rarr;<td>BLOB
35680 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
35690 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
356a0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c  lumn_double</b><
356b0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41  td>&rarr;<td>REA
356c0 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  L result.** <tr>
356d0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
356e0 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64  olumn_int</b><td
356f0 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69  >&rarr;<td>32-bi
35700 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
35710 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35730 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  t64</b><td>&rarr
35740 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45  ;<td>64-bit INTE
35750 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
35760 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
35770 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e  _column_text</b>
35780 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
35790 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a  F-8 TEXT result.
357a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
357b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
357c0 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  t16</b><td>&rarr
357d0 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54  ;<td>UTF-16 TEXT
357e0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
357f0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35800 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74  lumn_value</b><t
35810 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20  d>&rarr;<td>The 
35820 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a  result as an .**
35830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c   [sqlite3_value|
35840 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35850 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35860 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e  t..** <tr><td>&n
35870 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  bsp;<td>&nbsp;<t
35880 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e  d>&nbsp;.** <tr>
35890 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
358a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c  olumn_bytes</b><
358b0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a  td>&rarr;<td>Siz
358c0 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f  e of a BLOB.** o
358d0 72 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72  r a UTF-8 TEXT r
358e0 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a  esult in bytes.*
358f0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
35900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35910 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  s16&nbsp;&nbsp;<
35920 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72  /b>.** <td>&rarr
35930 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64  ;&nbsp;&nbsp;<td
35940 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a  >Size of UTF-16.
35950 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73  ** TEXT in bytes
35960 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
35970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
35980 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  pe</b><td>&rarr;
35990 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64  <td>Default.** d
359a0 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72  atatype of the r
359b0 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65  esult.** </table
359c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
359d0 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a  *.** <b>Details:
359e0 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  </b>.**.** ^Thes
359f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
35a00 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
35a10 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
35a20 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
35a30 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
35a40 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
35a50 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
35a60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35a70 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
35a80 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
35a90 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
35aa0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
35ab0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
35ac0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
35ad0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
35ae0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
35af0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
35b00 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
35b10 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
35b20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
35b30 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
35b40 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
35b50 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
35b60 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
35b70 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
35b80 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
35b90 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
35ba0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
35bb0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
35bc0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
35bd0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
35be0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
35bf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
35c00 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
35c10 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
35c20 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
35c30 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
35c40 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
35c50 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
35c60 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
35c70 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
35c80 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
35c90 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
35ca0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
35cb0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
35cc0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
35cd0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
35ce0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
35cf0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
35d00 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
35d10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35d20 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
35d30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
35d40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
35d50 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
35d60 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
35d70 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
35d80 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
35d90 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
35da0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
35db0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
35dc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
35dd0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
35de0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
35df0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
35e00 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
35e10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
35e20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
35e30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
35e40 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
35e50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35e60 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
35e70 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
35e80 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
35e90 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
35ea0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
35eb0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
35ec0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
35ed0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  d..**.** The fir
35ee0 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
35ef0 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c  s (_blob, _doubl
35f00 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c  e, _int, _int64,
35f10 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78   _text, and _tex
35f20 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74  t16).** each ret
35f30 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  urn the value of
35f40 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
35f50 20 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64   in a specific d
35f60 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a  ata format.  If.
35f70 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  ** the result co
35f80 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74  lumn is not init
35f90 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71  ially in the req
35fa0 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66  uested format (f
35fb0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
35fc0 66 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75  f the query retu
35fd0 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62  rns an integer b
35fe0 75 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ut the sqlite3_c
35ff0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74  olumn_text() int
36000 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65  erface.** is use
36010 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
36020 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20   value) then an 
36030 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
36040 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
36050 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  formed..**.** ^T
36060 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
36070 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
36080 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
36090 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
360a0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
360b0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
360c0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
360d0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
360e0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
360f0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
36100 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
36110 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
36120 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
36130 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
36140 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
36150 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72  _NULL]..** The r
36160 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73  eturn value of s
36170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
36180 70 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64  pe() can be used
36190 20 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68   to decide which
361a0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74  .** of the first
361b0 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73   six interface s
361c0 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f  hould be used to
361d0 20 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c   extract the col
361e0 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68  umn value..** Th
361f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
36200 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36210 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
36220 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
36230 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  no.** automatic 
36240 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
36250 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66   have occurred f
36260 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20  or the value in 
36270 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41  question.  .** A
36280 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
36290 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75  ersion, the resu
362a0 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71  lt of calling sq
362b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
362c0 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  e().** is undefi
362d0 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d  ned, though harm
362e0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a  less.  Future.**
362f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
36300 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
36310 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
36320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
36330 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
36340 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
36350 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
36360 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
36370 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72  OB or a TEXT str
36380 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ing, then the sq
36390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
363a0 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  es().** or sqlit
363b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
363c0 36 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63  6() interfaces c
363d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
363e0 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
363f0 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42  .** of that BLOB
36400 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a   or string..**.*
36410 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
36420 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
36430 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
36440 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
36450 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
36460 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
36470 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36480 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
36490 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
364a0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
364b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
364c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
364d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
364e0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
364f0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
36500 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
36510 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36520 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
36530 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
36540 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
36550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36560 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
36570 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
36580 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
36590 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
365a0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
365b0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
365c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
365d0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
365e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
365f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
36600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36610 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
36620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
36630 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
36640 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
36650 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
36660 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36670 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
36680 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
36690 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
366a0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
366b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
366c0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
366d0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
366e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
366f0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
36700 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
36710 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
36720 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
36730 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
36740 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
36750 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
36760 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
36770 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
36780 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
36790 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
367a0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
367b0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
367c0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
367d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
367e0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
367f0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
36800 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
36810 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
36820 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
36830 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
36840 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
36850 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
36860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36870 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
36880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36890 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
368a0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
368b0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
368c0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
368d0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
368e0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
368f0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
36900 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
36910 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
36920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36930 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
36940 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
36950 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
36960 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
36970 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
36980 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
36990 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
369a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
369b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
369c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
369d0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
369e0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
369f0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
36a00 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
36a10 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
36a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36a30 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
36a40 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
36a50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
36a60 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
36a70 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
36a80 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
36a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
36aa0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
36ab0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36ac0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36ad0 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
36ae0 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
36af0 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
36b00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36b10 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
36b20 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
36b30 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
36b40 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
36b50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
36b60 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
36b70 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
36b80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36b90 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
36ba0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
36bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
36bc0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
36bd0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
36be0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
36bf0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
36c00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36c10 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
36c20 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
36c30 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
36c40 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
36c50 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
36c60 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
36c70 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71  ** Hence, the sq
36c80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
36c90 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ue() interface.*
36ca0 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e  * is normally on
36cb0 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e  ly useful within
36cc0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
36cd0 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c  ion of .** [appl
36ce0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
36d00 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
36d10 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a  s], not within.*
36d20 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c  * top-level appl
36d30 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a  ication code..**
36d40 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f  .** The these ro
36d50 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d  utines may attem
36d60 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
36d70 65 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  e datatype of th
36d80 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f  e result..** ^Fo
36d90 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  r example, if th
36da0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
36db0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
36dc0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
36dd0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
36de0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
36df0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
36e00 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
36e10 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
36e20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
36e30 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
36e40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
36e50 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
36e60 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
36e70 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
36e80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
36e90 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
36ea0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
36eb0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
36ec0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
36ed0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
36ee0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
36ef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
36f00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
36f10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
36f20 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
36f30 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
36f40 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
36f50 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
36f60 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
36f70 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
36f80 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
36f90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
36fa0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
36fb0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
36fc0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
36fd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
36fe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
36ff0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
37000 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
37010 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
37020 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
37030 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
37040 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
37050 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
37060 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
37070 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
37080 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
37090 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
370a0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
370b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
370c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
370d0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
370e0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
370f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
37100 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
37110 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
37120 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
37130 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
37140 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
37150 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
37160 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
37170 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
37180 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
37190 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
371a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
371b0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
371c0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
371d0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
371e0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
371f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
37200 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
37210 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
37220 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
37230 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
37240 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
37250 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
37260 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
37270 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
37280 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
37290 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
372a0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
372b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
372c0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
372d0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
372e0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
372f0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
37300 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
37310 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
37320 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
37330 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
37340 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
37350 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
37360 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
37370 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
37380 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
37390 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
373a0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
373b0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
373c0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
373d0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
373e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
373f0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
37400 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
37410 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
37420 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
37430 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
37440 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
37450 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
37460 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
37470 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
37480 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
37490 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
374a0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
374b0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
374c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
374d0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
374e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
374f0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
37500 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
37510 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
37520 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
37530 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
37540 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
37550 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
37560 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
37570 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
37580 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
37590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
375a0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
375b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
375c0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
375d0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
375e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
375f0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
37600 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
37610 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
37620 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
37630 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
37640 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
37650 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
37660 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
37670 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
37680 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
37690 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
376a0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
376b0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
376c0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
376d0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
376e0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
376f0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
37700 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
37710 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
37720 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
37730 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
37740 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
37750 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
37760 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
37770 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
37780 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
37790 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
377a0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
377b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
377c0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
377d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
377e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
377f0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
37800 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
37810 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
37820 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
37830 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
37840 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
37850 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
37860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37870 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
37880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37890 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
378a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
378b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
378c0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
378d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
378e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
378f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37900 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
37910 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
37920 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
37930 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
37940 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
37950 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
37960 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
37970 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
37980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37990 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
379a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
379b0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
379c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
379d0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
379e0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
379f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37a00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
37a10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
37a20 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
37a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37a40 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
37a50 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
37a60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37a70 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
37a80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
37a90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
37aa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
37ab0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
37ac0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
37ad0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
37ae0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
37af0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
37b00 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
37b10 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
37b20 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
37b30 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
37b40 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
37b50 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
37b60 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
37b70 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
37b80 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
37b90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
37ba0 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20  Do not pass the 
37bb0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
37bc0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
37bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
37be0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
37bf0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
37c00 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
37c10 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
37c20 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   As long as the 
37c30 69 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73  input parameters
37c40 20 61 72 65 20 63 6f 72 72 65 63 74 2c 20 74 68   are correct, th
37c50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ese routines wil
37c60 6c 20 6f 6e 6c 79 0a 2a 2a 20 66 61 69 6c 20 69  l only.** fail i
37c70 66 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  f an out-of-memo
37c80 72 79 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ry error occurs 
37c90 64 75 72 69 6e 67 20 61 20 66 6f 72 6d 61 74 20  during a format 
37ca0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 4f  conversion..** O
37cb0 6e 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  nly the followin
37cc0 67 20 73 75 62 73 65 74 20 6f 66 20 69 6e 74 65  g subset of inte
37cd0 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65  rfaces are subje
37ce0 63 74 20 74 6f 20 6f 75 74 2d 6f 66 2d 6d 65 6d  ct to out-of-mem
37cf0 6f 72 79 0a 2a 2a 20 65 72 72 6f 72 73 3a 0a 2a  ory.** errors:.*
37d00 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
37d10 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  > sqlite3_column
37d20 5f 62 6c 6f 62 28 29 0a 2a 2a 20 3c 6c 69 3e 20  _blob().** <li> 
37d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37d40 65 78 74 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71  ext().** <li> sq
37d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37d60 74 31 36 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71  t16().** <li> sq
37d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37d80 65 73 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  es().** <li> sql
37d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37da0 73 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  s16().** </ul>.*
37db0 2a 0a 2a 2a 20 49 66 20 61 6e 20 6f 75 74 2d 6f  *.** If an out-o
37dc0 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f  f-memory error o
37dd0 63 63 75 72 73 2c 20 74 68 65 6e 20 74 68 65 20  ccurs, then the 
37de0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
37df0 6d 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  m these.** routi
37e00 6e 65 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  nes is the same 
37e10 61 73 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  as if the column
37e20 20 68 61 64 20 63 6f 6e 74 61 69 6e 65 64 20 61   had contained a
37e30 6e 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65  n SQL NULL value
37e40 2e 0a 2a 2a 20 56 61 6c 69 64 20 53 51 4c 20 4e  ..** Valid SQL N
37e50 55 4c 4c 20 72 65 74 75 72 6e 73 20 63 61 6e 20  ULL returns can 
37e60 62 65 20 64 69 73 74 69 6e 67 75 69 73 68 65 64  be distinguished
37e70 20 66 72 6f 6d 20 6f 75 74 2d 6f 66 2d 6d 65 6d   from out-of-mem
37e80 6f 72 79 20 65 72 72 6f 72 73 0a 2a 2a 20 62 79  ory errors.** by
37e90 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 5b 73   invoking the [s
37ea0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
37eb0 5d 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ] immediately af
37ec0 74 65 72 20 74 68 65 20 73 75 73 70 65 63 74 0a  ter the suspect.
37ed0 2a 2a 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  ** return value 
37ee0 69 73 20 6f 62 74 61 69 6e 65 64 20 61 6e 64 20  is obtained and 
37ef0 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 6f 74  before any.** ot
37f00 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
37f10 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 6f  face is called o
37f20 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
37f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37f40 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
37f50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
37f60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
37f70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
37f80 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
37f90 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
37fa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
37fb0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
37fc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
37fd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
37fe0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
37ff0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
38000 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
38010 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
38020 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
38030 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
38040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
38050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
38060 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
38070 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
38080 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
38090 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
380a0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
380b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
380c0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
380d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
380e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
380f0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
38100 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
38110 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
38120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
38130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
38140 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
38150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
38160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
38170 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
38180 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
38190 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
381a0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
381b0 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
381c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
381d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
381e0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
381f0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
38200 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
38210 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
38220 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
38230 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
38240 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
38250 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
38260 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
38270 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
38280 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
38290 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
382a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
382b0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
382c0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
382d0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
382e0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
382f0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
38300 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
38310 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
38320 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
38330 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
38340 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
38350 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
38360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
38370 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
38380 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
38390 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
383a0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
383b0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
383c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
383d0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
383e0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
383f0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
38400 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
38410 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
38420 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
38430 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
38440 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
38450 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
38460 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
38470 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
38480 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
38490 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
384a0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
384b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
384c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
384d0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
384e0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
384f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
38500 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
38510 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38520 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
38530 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
38540 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
38550 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
38560 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
38570 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
38580 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
38590 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
385a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
385b0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
385c0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
385d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
385e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
385f0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
38600 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
38610 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
38620 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
38630 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
38640 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
38650 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
38660 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
38670 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
38680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38690 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
386a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
386b0 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
386c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
386d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
386e0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
386f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
38700 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
38710 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
38720 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
38730 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
38740 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
38750 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
38760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
38770 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
38780 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to