/ Hex Artifact Content
Login

Artifact 039e1741797f8ecd72c9343667b74ae59e118c25ab04284aac4a8e5422fc5d1a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6940: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54  TE_OPEN_FILEPROT
6950: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20  ECTION_MASK     
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72  700000../* Reser
6990: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
69c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
69d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
69e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
69f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6a00: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6a10: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6a20: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6a30: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6a40: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6a50: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6a60: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6a70: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6a80: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6a90: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6aa0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6ab0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6ac0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6ad0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6ae0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6b10: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6b20: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6b30: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6b40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6b50: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6b60: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6b70: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6b80: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6b90: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6ba0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6bb0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6bc0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6bd0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6be0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6c00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c10: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6c20: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6c30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6c40: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6c50: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6c60: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6c70: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6c80: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6c90: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6ca0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6cc0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6cd0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6ce0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6cf0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6d00: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6d10: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6d20: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6d30: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6d50: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6d60: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6d70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6d80: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6d90: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6da0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6db0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6dc0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6dd0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6de0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6df0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6e00: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6e10: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6e20: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6e40: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6e50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6e60: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6e70: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6e80: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69  icates that a fi
6e90: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6ea0: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6eb0: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6ec0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6ed0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6ee0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6ef0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6f00: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6f10: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6f20: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6f30: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6f40: 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  ivileges..**.** 
6f50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6f60: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72  _BATCH_ATOMIC pr
6f70: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6f80: 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  t the underlying
6f90: 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73  .** filesystem s
6fa0: 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75  upports doing mu
6fb0: 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65  ltiple write ope
6fc0: 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c  rations atomical
6fd0: 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a  ly when those.**
6fe0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6ff0: 73 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20  s are bracketed 
7000: 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  by [SQLITE_FCNTL
7010: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
7020: 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  ITE] and.** [SQL
7030: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
7040: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
7050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7060: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7080: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
7090: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70a0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
70b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
70c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
70e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
70f0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
7100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7110: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
7120: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7140: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
7150: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7160: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
7170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7180: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
7190: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
71a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
71c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
71d0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
71e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
71f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7200: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
7210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7220: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
7230: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
7240: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7250: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7260: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
7270: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
7280: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7290: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
72a0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
72b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
72c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
72d0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
72e0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
72f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
7300: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
7310: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
7320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7330: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
7340: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7350: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
7360: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
7370: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
7380: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
7390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
73a0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
73b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
73c0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
73d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
73e0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
73f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
7400: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
7410: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
7420: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
7430: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
7440: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7450: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
7460: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
7470: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
7480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7490: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
74c0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
74d0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
74e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
74f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
7500: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
7510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
7520: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
7530: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
7540: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
7550: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
7560: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
7570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7580: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
7590: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
75a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
75b0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
75c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
75d0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
75e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
75f0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
7600: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
7610: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
7620: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
7630: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
7640: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
7650: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
7660: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
7670: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
7680: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7690: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
76a0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
76b0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
76c0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
76d0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
76e0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
76f0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7700: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7710: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7720: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7730: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7740: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7750: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7760: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7770: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
7780: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
77a0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
77b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77c0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
77d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77e0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
77f0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7800: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7810: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7820: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7830: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7840: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7850: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7860: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7870: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
7880: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7890: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
78a0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
78b0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
78c0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
78d0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
78e0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
78f0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7900: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7910: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7920: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7930: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7940: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7950: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7960: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7970: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
7980: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
7990: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
79a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
79b0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
79c0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
79d0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
79e0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
79f0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7a00: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7a10: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7a20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7a30: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7a40: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7a60: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7a70: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
7aa0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7ab0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7ac0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
7ad0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7ae0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7af0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7b00: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7b10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7b20: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7b30: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7b40: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7b50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7b60: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7b70: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
7b80: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
7b90: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
7ba0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
7bb0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
7bc0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
7bd0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7be0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7bf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7c00: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7c10: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7c20: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7c30: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7c40: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7c50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7c60: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7c70: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
7c80: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
7c90: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
7ca0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7cb0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
7cc0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
7cd0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7cf0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7d00: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7d10: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7d20: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7d30: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7d40: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7d50: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7d70: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
7d80: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
7d90: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
7da0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7db0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
7dc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
7dd0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7de0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7df0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7e00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7e10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7e20: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7e30: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7e40: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7e50: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7e60: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7e70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
7e80: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e90: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
7ea0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7eb0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
7ec0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
7ed0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7ee0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7ef0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7f00: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7f10: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7f20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7f30: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7f40: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7f50: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7f60: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7f70: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
7f80: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
7f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7fa0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
7fb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7fc0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
7fd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7fe0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7ff0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
8000: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8010: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
8020: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
8030: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
8040: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
8050: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
8060: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
8070: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
8080: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
8090: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
80a0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
80b0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
80c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
80d0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
80e0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
80f0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
8100: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
8110: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
8120: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
8130: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
8140: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
8150: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
8160: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
8170: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
8180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8190: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
81a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
81b0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
81d0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
81f0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
8200: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8210: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
8220: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
8230: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
8240: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
8250: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
8260: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
8270: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
8280: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
8290: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
82a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
82b0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
82c0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
82d0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
82e0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
82f0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
8300: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
8310: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
8320: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
8330: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
8340: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
8350: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
8360: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
8380: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
8390: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
83a0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
83b0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
83c0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
83d0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
83e0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
83f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
8400: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
8410: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
8420: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
8430: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
8440: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
8450: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
8460: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
8470: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
8480: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
8490: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
84a0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
84b0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
84c0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
84d0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
84e0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
84f0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
8500: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
8510: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
8520: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
8530: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
8540: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
8550: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
8560: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
8570: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
8580: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
8590: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
85a0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
85b0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
85c0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
85d0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
85e0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
85f0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
8600: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
8610: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
8620: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
8630: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
8640: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
8650: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
8660: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
8670: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
8680: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8690: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
86a0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
86b0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
86c0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
86d0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
86e0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
86f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
8700: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
8710: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8720: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
8730: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
8740: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
8750: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
8760: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
8770: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
8780: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
8790: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
87a0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
87b0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
87c0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
87d0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
87e0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
87f0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
8800: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
8810: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
8820: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
8830: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8840: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
8850: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
8860: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
8870: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
8880: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8890: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
88a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
88b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
88d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
88e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
88f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8900: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
8910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8920: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
8930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8940: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
8950: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8960: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8980: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
8990: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
89a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
89b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
89c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
89d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
89e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
89f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8a00: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
8a10: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c  _WHEN_OPEN].** <
8a20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8a30: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
8a40: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  WRITE].** <li> [
8a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
8a60: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  UTABLE].** <li> 
8a70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41  [SQLITE_IOCAP_BA
8a80: 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  TCH_ATOMIC].** <
8a90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
8ac0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
8ad0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8ae0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8b00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8b10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8b20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
8b30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
8b40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
8b50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
8b60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
8b70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
8b80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8b90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8bb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
8bc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
8bd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8be0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8bf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8c00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8c10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8c20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
8c30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
8c40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
8c50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
8c60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8c70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8c80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8c90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8ca0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8cb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8cc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8cd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8ce0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8cf0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8d00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8d10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8d20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
8d30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
8d40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
8d50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
8d60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8d70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
8d80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8d90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8da0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8db0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8dc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8dd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8de0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8df0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8e00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8e10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8e30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8e40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8e50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8e70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8e80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8e90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8ea0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8eb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8ec0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8ed0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8ee0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8ef0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8f00: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8f10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8f30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8f40: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8f50: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8f60: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8f70: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8f80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f90: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8fa0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8fb0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8fc0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8fd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8fe0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8ff0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
9000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9010: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
9020: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
9030: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
9040: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
9050: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
9060: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
9070: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
9080: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
9090: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
90a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
90b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
90c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
90d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
90e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
90f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
9100: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
9110: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
9120: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
9130: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
9140: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
9150: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
9160: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
9170: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
9180: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
9190: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
91a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
91b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
91c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
91d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
91e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
91f0: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
9200: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9210: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
9220: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
9230: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
9240: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
9250: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9260: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
9270: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
9280: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9290: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
92a0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
92b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
92c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
92d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
92e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
92f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
9300: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69  ** KEYWORDS: {fi
9320: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
9330: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  es} {file contro
9340: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  l opcode}.**.** 
9350: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9360: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
9370: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
9390: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
93a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
93b0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
93c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
93d0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
93e0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c  terface..**.** <
93f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
9410: 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ATE]].** The [SQ
9420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
9430: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
9440: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
9450: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
9460: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
9470: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
9480: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
9490: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
94a0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
94b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
94c0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
94d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
94e0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
94f0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
9500: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
9510: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
9520: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
9530: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
9540: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
9550: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
9560: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
9570: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
9580: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
9590: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
95a0: 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54  e when the SQLIT
95b0: 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c  E_TEST.** compil
95c0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
95d0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   used..**.** <li
95e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
95f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
9600: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9610: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
9620: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
9630: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
9640: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
9650: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
9660: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
9670: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
9680: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
9690: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
96a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
96b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
96c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
96d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
96e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
96f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
9700: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
9710: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
9720: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
9730: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
9740: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
9750: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
9780: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
9790: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
97a0: 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20  _LIMIT]].** The 
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
97c0: 5a 45 5f 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65  ZE_LIMIT] opcode
97d0: 20 69 73 20 75 73 65 64 20 62 79 20 69 6e 2d 6d   is used by in-m
97e0: 65 6d 6f 72 79 20 56 46 53 20 74 68 61 74 0a 2a  emory VFS that.*
97f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71  * implements [sq
9800: 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a  lite3_deserializ
9810: 65 28 29 5d 20 74 6f 20 73 65 74 20 61 6e 20 75  e()] to set an u
9820: 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
9830: 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65  e size.** of the
9840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
9850: 61 73 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ase.  The argume
9860: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9870: 74 6f 20 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e  to a [sqlite3_in
9880: 74 36 34 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  t64]..** If the 
9890: 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20  integer pointed 
98a0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
98b0: 74 68 65 6e 20 69 74 20 69 73 20 66 69 6c 6c 65  then it is fille
98c0: 64 20 69 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  d in with the.**
98d0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20   current limit. 
98e0: 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 6c   Otherwise the l
98f0: 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 74  imit is set to t
9900: 68 65 20 6c 61 72 67 65 72 20 6f 66 20 74 68 65  he larger of the
9910: 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
9920: 20 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64   integer pointed
9930: 20 74 6f 20 61 6e 64 20 74 68 65 20 63 75 72 72   to and the curr
9940: 65 6e 74 20 64 61 74 61 62 61 73 65 20 73 69 7a  ent database siz
9950: 65 2e 20 20 54 68 65 20 69 6e 74 65 67 65 72 0a  e.  The integer.
9960: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ** pointed to is
9970: 20 73 65 74 20 74 6f 20 74 68 65 20 6e 65 77 20   set to the new 
9980: 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  limit..**.** <li
9990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
99a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
99b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
99c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
99d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
99e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
99f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9a00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9a10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9a20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9a30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9a40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9a50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9a60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9a70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9a80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9a90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9aa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9ab0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9ac0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9ad0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9ae0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9af0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9b00: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9b10: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9b20: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9b30: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9b40: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9b50: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9b60: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9b70: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9b80: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9ba0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9bb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9bc0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9bd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9be0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9bf0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9c00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9c10: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9c20: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9c30: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9c40: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9c50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9c60: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9c70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c80: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9c90: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
9ca0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cb0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9cc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9cd0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9ce0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9cf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9d00: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9d10: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9d20: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9d30: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9d40: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9d50: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9d60: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9d70: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9d80: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9d90: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9da0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9dd0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9de0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9df0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9e00: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9e10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9e20: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9e30: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9e40: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9e50: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9e60: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9e70: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9e80: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9e90: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9ea0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9eb0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9ec0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9ed0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9ee0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9ef0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9f00: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9f10: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9f20: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9f30: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9f40: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9f50: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9f60: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9f70: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9f80: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9f90: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9fa0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9fb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9fc0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9fe0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9ff0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
a000: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
a010: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
a020: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
a030: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
a040: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
a050: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
a060: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
a070: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
a080: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
a090: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
a0a0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
a0b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
a0c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
a0d0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
a0e0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
a0f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a100: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
a110: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
a120: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
a130: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
a140: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
a150: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
a160: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
a170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a180: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
a190: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
a1b0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
a1c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
a1d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
a1e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
a1f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
a200: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
a210: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
a220: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
a230: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
a240: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
a250: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
a260: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
a270: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
a280: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
a290: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
a2a0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
a2b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
a2c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a2d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
a2e0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
a2f0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
a300: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
a310: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
a320: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
a330: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
a340: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a360: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
a370: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a380: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
a390: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
a3a0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
a3b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
a3c0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
a3d0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
a3e0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
a3f0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
a400: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
a410: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
a420: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
a430: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
a440: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
a450: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
a460: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
a470: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
a480: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
a490: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
a4a0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
a4b0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
a4c0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
a4d0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
a4e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
a4f0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
a500: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
a510: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
a520: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
a530: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
a540: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
a550: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
a560: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
a570: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
a580: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
a590: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
a5a0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
a5b0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
a5c0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
a5d0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
a5e0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
a5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
a600: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
a610: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
a620: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
a630: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
a640: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
a650: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
a660: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
a670: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
a680: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
a690: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
a6a0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
a6b0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
a6c0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
a6d0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
a6e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
a6f0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
a700: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
a710: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
a720: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
a730: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
a740: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
a750: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
a760: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
a770: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
a780: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
a790: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
a7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a7b0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a7c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a7d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a7e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
a7f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a800: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a810: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a820: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a830: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a840: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a850: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a860: 20 6c 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d   log ([WAL file]
a870: 29 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  ) and shared mem
a880: 6f 72 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65  ory.** files use
a890: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a8a0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a8b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a8c0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a8d0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a8e0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a8f0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a900: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a910: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a920: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a930: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a940: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a950: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a960: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a970: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a980: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a990: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a9a0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a9b0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a9c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9d0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a9e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a9f0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
aa00: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
aa10: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
aa20: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
aa30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
aa40: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
aa50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
aa60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
aa70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
aa80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
aa90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
aaa0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
aab0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
aac0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
aad0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
aae0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
aaf0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
ab00: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
ab10: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ab20: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ab30: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ab40: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ab50: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
ab60: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
ab70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab80: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ab90: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abb0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
abc0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
abd0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
abe0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
abf0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
ac00: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
ac10: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
ac20: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
ac30: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
ac50: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
ac60: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
ac70: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
ac80: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
ac90: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
aca0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
acb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
acc0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
acd0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
ace0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
acf0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
ad00: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
ad10: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
ad20: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
ad30: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
ad40: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
ad50: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ad60: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ad70: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ad80: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ad90: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
ada0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
adb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
adc0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
add0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ade0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
adf0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
ae00: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
ae10: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
ae20: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
ae30: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
ae40: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
ae50: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
ae60: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
ae70: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
ae80: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
ae90: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
aea0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
aeb0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
aec0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
aed0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
aee0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
aef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af00: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
af10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af20: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
af30: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
af40: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
af50: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
af60: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
af70: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
af80: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
af90: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
afa0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
afb0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
afc0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
afd0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
afe0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
aff0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
b000: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
b010: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
b020: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
b030: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
b040: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b050: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
b060: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
b070: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
b080: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
b090: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
b0a0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
b0b0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
b0c0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
b0d0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
b0e0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
b0f0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
b100: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
b110: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
b120: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
b130: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
b140: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
b150: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b160: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
b170: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
b180: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
b190: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
b1a0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
b1b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b1d0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
b1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
b1f0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
b200: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
b210: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
b220: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
b230: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
b240: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
b250: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
b260: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
b270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b280: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
b290: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
b2a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
b2b0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
b2c0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
b2d0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
b2e0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
b2f0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
b300: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
b310: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
b320: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
b330: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
b340: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
b350: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
b380: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
b390: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
b3a0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
b3b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b3c0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b3d0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
b3e0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
b3f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
b400: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
b410: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b420: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
b430: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
b440: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
b450: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
b460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b470: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b480: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
b490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
b4a0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
b4b0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
b4c0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
b4d0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
b4e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b4f0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
b500: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
b510: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
b520: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
b530: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
b540: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
b550: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
b560: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
b570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b580: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b590: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
b5a0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
b5b0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
b5c0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
b5d0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
b5e0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
b5f0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
b600: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
b610: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
b620: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
b630: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
b640: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
b650: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
b660: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
b670: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
b680: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
b690: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b6a0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b6b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b6c0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
b6d0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
b6e0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
b6f0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
b700: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b710: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b720: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b730: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
b740: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
b750: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b760: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b770: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b780: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b790: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b7a0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b7b0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
b7c0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
b7d0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
b7e0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
b7f0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
b800: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b810: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b820: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b830: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b840: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b850: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b860: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b870: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b880: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b890: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b8a0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b8b0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b8c0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b8d0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b8e0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b8f0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b900: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b910: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b940: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b950: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b960: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b970: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b980: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b990: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b9a0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b9b0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b9d0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b9e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ba00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ba10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ba20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ba30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ba40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ba50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
ba60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ba70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ba80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ba90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
baa0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
bab0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
bac0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
bad0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
bae0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
baf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
bb00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
bb10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
bb20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
bb30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
bb40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
bb50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
bb60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
bb70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
bb80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
bba0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
bbb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
bbc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
bbd0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
bbe0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
bbf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
bc00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
bc10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
bc20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
bc30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
bc40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
bc50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
bc60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
bc70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bc80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
bc90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
bca0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
bcb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
bcc0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bcd0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
bce0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
bcf0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
bd00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
bd10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
bd20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
bd30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
bd40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
bd50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bd60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
bd70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
bd80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
bd90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
bda0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
bdb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
bdc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
bdd0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
bde0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
bdf0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
be00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
be10: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
be20: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
be30: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
be40: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
be50: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
be60: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
be80: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
be90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
bea0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
beb0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
bec0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
bed0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
bee0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
bef0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
bf00: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
bf10: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
bf20: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
bf30: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
bf40: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
bf50: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
bf60: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
bf70: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bf80: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
bf90: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
bfa0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
bfb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
bfc0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
bfd0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
bfe0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
bff0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
c000: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
c010: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
c020: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
c030: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
c040: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
c050: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
c060: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
c070: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
c080: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
c090: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
c0a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
c0b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
c0c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c0d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
c0e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c0f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
c100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
c110: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
c120: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
c130: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
c140: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
c150: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
c160: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
c170: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
c180: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
c190: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
c1a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
c1b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
c1c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
c1d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
c1e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
c1f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
c200: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
c210: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
c220: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
c230: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
c240: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
c250: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
c260: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
c270: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
c280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c290: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
c2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c2b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
c2c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
c2d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c2e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
c2f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
c300: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
c310: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
c320: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
c330: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
c340: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
c350: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
c360: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
c370: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
c380: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
c390: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c3b0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
c3c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c3d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c3e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
c3f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
c400: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
c410: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
c420: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
c430: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
c440: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
c450: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
c460: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c470: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
c480: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
c490: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
c4a0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
c4b0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
c4c0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
c4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4e0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
c4f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c500: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c510: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
c520: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c530: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c540: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c550: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c560: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
c570: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
c580: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
c590: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
c5a0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
c5b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
c5c0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
c5d0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
c5e0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
c5f0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
c600: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
c610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c630: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
c640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
c650: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
c660: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
c670: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
c680: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
c690: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
c6a0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
c6b0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
c6c0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
c6d0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
c6e0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
c6f0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
c700: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
c710: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
c720: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
c730: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
c740: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
c750: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
c760: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
c770: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
c780: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c790: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c7b0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
c7c0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c7d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c7e0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
c7f0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
c800: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c810: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c820: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c830: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c840: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c850: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c870: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c880: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c890: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c8a0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c8b0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c8c0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c8d0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c8e0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c8f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c910: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c920: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
c930: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
c940: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c950: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c960: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
c970: 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  OK, then.** the 
c980: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c990: 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61  is placed in "ba
c9a0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c  tch write mode",
c9b0: 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20   which.** means 
c9c0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
c9d0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
c9e0: 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64  will be deferred
c9f0: 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f   and done.** ato
ca00: 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e  mically at the n
ca10: 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ext [SQLITE_FCNT
ca20: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
ca30: 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73  WRITE].  Systems
ca40: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  .** that do not 
ca50: 73 75 70 70 6f 72 74 20 62 61 74 63 68 20 61 74  support batch at
ca60: 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c  omic writes will
ca70: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
ca80: 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c  OTFOUND..** ^Fol
ca90: 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65 73 73  lowing a success
caa0: 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ful SQLITE_FCNTL
cab0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
cac0: 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f  ITE and prior to
cad0: 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20  .** the closing 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
caf0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
cb00: 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  E] or.** [SQLITE
cb10: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cb20: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53  ATOMIC_WRITE], S
cb30: 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a  QLite will make.
cb40: 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66  ** no VFS interf
cb50: 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65  ace calls on the
cb60: 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66   same [sqlite3_f
cb70: 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69  ile] file descri
cb80: 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66  ptor.** except f
cb90: 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  or calls to the 
cba0: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e  xWrite method an
cbb0: 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  d the xFileContr
cbc0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74  ol method.** wit
cbd0: 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  h [SQLITE_FCNTL_
cbe0: 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a  SIZE_HINT]..**.*
cbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cc00: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
cc10: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68  IC_WRITE]].** Th
cc20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cc30: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cc40: 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  ITE] opcode caus
cc50: 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20  es all write.** 
cc60: 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65  operations since
cc70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75   the previous su
cc80: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
cc90: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e   .** [SQLITE_FCN
cca0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
ccb0: 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72  WRITE] to be per
ccc0: 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c  formed atomicall
ccd0: 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  y..** This file 
cce0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ccf0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
cd00: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77  nd only if the w
cd10: 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c  rites were.** al
cd20: 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63  l performed succ
cd30: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76  essfully and hav
cd40: 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  e been committed
cd50: 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73   to persistent s
cd60: 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61  torage..** ^Rega
cd70: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
cd80: 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73  r or not it is s
cd90: 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20  uccessful, this 
cda0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cdb0: 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64  es.** the file d
cdc0: 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66  escriptor out of
cdd0: 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64   batch write mod
cde0: 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  e so that all su
cdf0: 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74  bsequent.** writ
ce00: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
ce10: 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a   independent..**
ce20: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
ce30: 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54  ver invoke SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
ce50: 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68  TOMIC_WRITE with
ce60: 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73  out.** a prior s
ce70: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ce80: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
ce90: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cea0: 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  TE]..**.** <li>[
ceb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
cec0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ced0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
cee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cef0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cf00: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cf10: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cf20: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cf30: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cf40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cf50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cf60: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cf70: 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64  TE] to be rolled
cf80: 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20   back..** ^This 
cf90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cfa0: 65 73 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  es the file desc
cfb0: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cfc0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a  tch write mode.*
cfd0: 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  * so that all su
cfe0: 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f  bsequent write o
cff0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
d000: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
d010: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
d020: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
d030: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
d040: 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f  OMIC_WRITE witho
d050: 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75  ut.** a prior su
d060: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
d070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
d080: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
d090: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  E]..**.** <li>[[
d0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d0b0: 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54  K_TIMEOUT]].** T
d0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d0d0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f  _LOCK_TIMEOUT] o
d0e0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 74 74  pcode causes att
d0f0: 65 6d 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a  empts to obtain.
d100: 2a 2a 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75  ** a file lock u
d110: 73 69 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f  sing the xLock o
d120: 72 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  r xShmLock metho
d130: 64 73 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f  ds of the VFS to
d140: 20 77 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20   wait.** for up 
d150: 74 6f 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  to M millisecond
d160: 73 20 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67  s before failing
d170: 2c 20 77 68 65 72 65 20 4d 20 69 73 20 74 68 65  , where M is the
d180: 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69   single .** unsi
d190: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 70 61 72  gned integer par
d1a0: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ameter..**.** <l
d1b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d1c0: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a  _DATA_VERSION]].
d1d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d1e0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
d1f0: 4e 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  N] opcode is use
d200: 64 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  d to detect chan
d210: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61  ges to.** a data
d220: 62 61 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20  base file.  The 
d230: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
d240: 69 6e 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69  inter to a 32-bi
d250: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
d260: 65 72 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61  er..** The "data
d270: 20 76 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68   version" for th
d280: 65 20 70 61 67 65 72 20 69 73 20 77 72 69 74 74  e pager is writt
d290: 65 6e 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e  en into the poin
d2a0: 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61  ter.  The.** "da
d2b0: 74 61 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e  ta version" chan
d2c0: 67 65 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ges whenever any
d2d0: 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74   change occurs t
d2e0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
d2f0: 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ing.** database 
d300: 66 69 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72  file, either thr
d310: 6f 75 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65  ough SQL stateme
d320: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
d330: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
d340: 65 63 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67  ection or throug
d350: 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  h transactions c
d360: 6f 6d 6d 69 74 74 65 64 20 62 79 20 73 65 70 61  ommitted by sepa
d370: 72 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  rate database.**
d380: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73   connections pos
d390: 73 69 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70  sibly in other p
d3a0: 72 6f 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73  rocesses. The [s
d3b0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
d3c0: 6e 67 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  nges()].** inter
d3d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
d3e0: 20 74 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20   to find if any 
d3f0: 64 61 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20  database on the 
d400: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63  connection has c
d410: 68 61 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74  hanged,.** but t
d420: 68 61 74 20 69 6e 74 65 72 66 61 63 65 20 72 65  hat interface re
d430: 73 70 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65  sponds to change
d440: 73 20 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c  s on TEMP as wel
d450: 6c 20 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f  l as MAIN and do
d460: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64  es.** not provid
d470: 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f  e a mechanism to
d480: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d490: 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41  to MAIN only.  A
d4a0: 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  lso, the.** [sql
d4b0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
d4c0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
d4d0: 72 65 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65  responds to inte
d4e0: 72 6e 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c  rnal changes onl
d4f0: 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63  y and.** omits c
d500: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f  hanges made by o
d510: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
d520: 6e 6e 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  nnections.  The.
d530: 2a 2a 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  ** [PRAGMA data_
d540: 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
d550: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61   provide a mecha
d560: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d570: 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73  hanges to.** a s
d580: 69 6e 67 6c 65 20 61 74 74 61 63 68 65 64 20 64  ingle attached d
d590: 61 74 61 62 61 73 65 20 74 68 61 74 20 6f 63 63  atabase that occ
d5a0: 75 72 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20  ur due to other 
d5b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d5c0: 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69  ions,.** but omi
d5d0: 74 73 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65  ts changes imple
d5e0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 64 61  mented by the da
d5f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d600: 6e 20 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73  n on which it is
d610: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69  .** called.  Thi
d620: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d630: 73 20 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61  s the only mecha
d640: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d650: 68 61 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68  hanges that.** h
d660: 61 70 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74  appen either int
d670: 65 72 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72  ernally or exter
d680: 6e 61 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61  nally and that a
d690: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
d6a0: 74 68 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c  th.** a particul
d6b0: 61 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ar attached data
d6c0: 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  base..** </ul>.*
d6d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d6e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d710: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d720: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
d730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d740: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
d750: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
d760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d770: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
d780: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d7a0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
d7b0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
d7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d7d0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
d7e0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d800: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
d810: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d830: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
d840: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
d850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
d860: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
d870: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
d880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
d890: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
d8a0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
d8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
d8c0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
d8d0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d8f0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
d900: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
d910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
d920: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
d930: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
d940: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d960: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
d970: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
d980: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
d990: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
d9a0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d9b0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
d9c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d9d0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da00: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
da10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
da20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
da30: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
da40: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
da50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
da60: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
da70: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
da80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da90: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
daa0: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
dab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dac0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
dad0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
dae0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
daf0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
db00: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
db10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
db20: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
db30: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
db40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
db50: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
db60: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
db70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
db80: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
db90: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
dba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
dbb0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
dbc0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
dbd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
dbe0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
dbf0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dc20: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
dc30: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
dc40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc50: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
dc60: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
dc70: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc80: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
dc90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
dca0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
dcb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dcc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
dcd0: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34  OUT           34
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcf0: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
dd00: 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35 0a  ON           35.
dd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dd20: 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20  CNTL_SIZE_LIMIT 
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 33 36 0a 0a              36..
dd40: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
dd50: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
dd60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
dd70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
dd80: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
dd90: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
ddb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ddc0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
ddd0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
dde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ddf0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
de00: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
de10: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
de20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
de30: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
de40: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
de50: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
de60: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
de70: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
de80: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
de90: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
dea0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
deb0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
dec0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
ded0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
dee0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
def0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
df00: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
df10: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
df20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
df30: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
df40: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
df50: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
df60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
df70: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
df80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
df90: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
dfa0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
dfb0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
dfc0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
dfd0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
dfe0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
dff0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
e000: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
e010: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
e020: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
e030: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
e040: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
e050: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
e060: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
e070: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
e080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
e090: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
e0a0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
e0b0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
e0c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e0d0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
e0e0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
e0f0: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
e100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
e110: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
e120: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
e130: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
e140: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
e150: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
e160: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
e170: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
e180: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
e190: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
e1a0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
e1b0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
e1c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
e1d0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
e1e0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
e1f0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
e200: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
e210: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
e220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
e230: 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65 72  ** The VFS inter
e240: 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65  face is sometime
e250: 73 20 65 78 74 65 6e 64 65 64 20 62 79 20 61 64  s extended by ad
e260: 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73  ding new methods
e270: 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64   onto.** the end
e280: 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73 75 63  .  Each time suc
e290: 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f  h an extension o
e2a0: 63 63 75 72 73 2c 20 74 68 65 20 69 56 65 72 73  ccurs, the iVers
e2b0: 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20  ion field.** is 
e2c0: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68  incremented.  Th
e2d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
e2e0: 20 73 74 61 72 74 65 64 20 6f 75 74 20 61 73 20   started out as 
e2f0: 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b  1 in.** SQLite [
e300: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f  version 3.5.0] o
e310: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d  n [dateof:3.5.0]
e320: 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64  , then increased
e330: 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51   to 2.** with SQ
e340: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
e350: 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a  7.0] on [dateof:
e360: 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e  3.7.0], and then
e370: 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f   increased.** to
e380: 20 33 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b   3 with SQLite [
e390: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f  version 3.7.6] o
e3a0: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d  n [dateof:3.7.6]
e3b0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
e3c0: 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  elds.** may be a
e3d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73  ppended to the s
e3e0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e3f0: 74 20 61 6e 64 20 74 68 65 20 69 56 65 72 73 69  t and the iVersi
e400: 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20  on value.** may 
e410: 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20 69  increase again i
e420: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
e430: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
e440: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
e450: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
e460: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
e470: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
e480: 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66  the transition f
e490: 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76  rom.** SQLite [v
e4a0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f  ersion 3.5.9] to
e4b0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d   [version 3.6.0]
e4c0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e   on [dateof:3.6.
e4d0: 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68  0].** and yet th
e4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
e4f0: 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65   was not modifie
e500: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
e510: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
e520: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
e530: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
e540: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
e550: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
e560: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
e570: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
e580: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
e590: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
e5a0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
e5b0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
e5c0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
e5d0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
e5e0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
e5f0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
e600: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
e610: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
e620: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
e630: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
e640: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
e650: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
e660: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
e670: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
e680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
e690: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
e6a0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
e6b0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
e6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
e6d0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
e6e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e6f0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
e700: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
e710: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
e720: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
e730: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
e740: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
e750: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
e760: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
e770: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
e780: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
e790: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
e7a0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
e7b0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
e7c0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
e7d0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e7e0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e7f0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
e800: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
e810: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
e820: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
e830: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
e840: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
e850: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
e860: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
e870: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
e880: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
e890: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
e8a0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
e8b0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
e8c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
e8d0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e8e0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
e8f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e900: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
e910: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
e920: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
e930: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
e940: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
e950: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
e960: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
e970: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
e980: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
e990: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
e9a0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
e9b0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
e9c0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
e9d0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
e9e0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
e9f0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
ea00: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
ea10: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ea20: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
ea30: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
ea40: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
ea50: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
ea60: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
ea70: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
ea80: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
ea90: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
eaa0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
eab0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
eac0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
ead0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
eae0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
eaf0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
eb00: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
eb10: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
eb20: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
eb30: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
eb40: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
eb50: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
eb60: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
eb70: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
eb80: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
eb90: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
eba0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ebb0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ebc0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
ebd0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ebe0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
ebf0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ec00: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ec10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
ec20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
ec30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
ec40: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
ec50: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
ec60: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
ec70: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
ec80: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
ec90: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
eca0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
ecb0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
ecc0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
ecd0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
ece0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
ecf0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
ed00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
ed10: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
ed20: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
ed30: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
ed40: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
ed50: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
ed60: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
ed70: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ed80: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ed90: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
eda0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
edb0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
edc0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
edd0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
ede0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
edf0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
ee00: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
ee10: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
ee20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee30: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
ee40: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee50: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
ee60: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee70: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ee80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ee90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
eea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
eeb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
eec0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
eed0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
eee0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
eef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef00: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
ef10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ef20: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
ef30: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
ef40: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
ef50: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
ef60: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
ef70: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ef80: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
ef90: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
efa0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
efb0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
efc0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
efd0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
efe0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
eff0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
f000: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
f010: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
f020: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
f030: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
f040: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
f050: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
f060: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
f070: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
f080: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
f090: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
f0a0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
f0b0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
f0c0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
f0d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
f0e0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
f0f0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
f100: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
f110: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
f120: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
f130: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
f140: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
f150: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
f160: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
f170: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
f180: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
f190: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f1a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
f1b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
f1c0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
f1d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f1e0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
f1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
f200: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
f210: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
f220: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
f230: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
f240: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
f250: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
f260: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f270: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
f280: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
f290: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
f2a0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
f2b0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
f2c0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
f2d0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
f2e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f2f0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
f300: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
f310: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
f320: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
f330: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
f340: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
f350: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
f360: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
f370: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
f380: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
f390: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
f3a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
f3b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
f3c0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
f3d0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
f3e0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
f3f0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
f400: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
f410: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
f420: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
f430: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
f440: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
f450: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
f460: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
f470: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f480: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f490: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
f4a0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
f4b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
f4c0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
f4d0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
f4e0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
f4f0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
f500: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
f510: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
f520: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
f530: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
f540: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
f550: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
f560: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
f570: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
f580: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
f590: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
f5a0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
f5b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
f5c0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
f5d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
f5e0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
f5f0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
f600: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
f610: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
f620: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
f630: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
f640: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
f650: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
f660: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
f670: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
f680: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
f690: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
f6a0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
f6b0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
f6c0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
f6d0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
f6e0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
f6f0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
f700: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
f710: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
f720: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
f730: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f740: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
f750: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
f760: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
f770: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f780: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
f790: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f7a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
f7b0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
f7c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f7d0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
f7e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f7f0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
f800: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
f810: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
f820: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
f830: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
f840: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
f850: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
f860: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
f870: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
f880: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
f890: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
f8a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
f8b0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
f8c0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
f8d0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
f8e0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
f8f0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
f900: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
f910: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
f920: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
f930: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
f940: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
f950: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
f960: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
f970: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
f980: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
f990: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
f9a0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
f9b0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
f9c0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
f9d0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
f9e0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
f9f0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
fa00: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
fa10: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fa20: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
fa30: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
fa40: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
fa50: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
fa60: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
fa70: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
fa80: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
fa90: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
faa0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
fab0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
fac0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
fad0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
fae0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
faf0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
fb00: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
fb10: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
fb20: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
fb30: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
fb40: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
fb50: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
fb60: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
fb70: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
fb80: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
fb90: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
fba0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
fbb0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
fbc0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
fbd0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
fbe0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
fbf0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
fc00: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
fc10: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
fc20: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
fc30: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
fc40: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
fc50: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
fc60: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
fc70: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
fc80: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
fc90: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
fca0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
fcb0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
fcc0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
fcd0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
fce0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
fcf0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
fd00: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
fd10: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
fd20: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
fd30: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
fd40: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
fd50: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
fd60: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
fd70: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
fd80: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
fd90: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
fda0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
fdb0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
fdc0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
fdd0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
fde0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
fdf0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
fe00: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
fe10: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
fe20: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
fe30: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
fe40: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
fe50: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
fe60: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
fe70: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
fe80: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
fe90: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
fea0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
feb0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
fec0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
fed0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
fee0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
fef0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
ff00: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
ff10: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
ff20: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
ff30: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
ff40: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
ff50: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
ff60: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
ff70: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
ff80: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
ff90: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
ffa0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
ffb0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
ffc0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
ffd0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
ffe0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
fff0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
10000 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
10010 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
10020 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
10030 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
10040 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
10050 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
10060 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
10070 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
10080 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
10090 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
100a0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
100b0 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
100c0 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
100d0 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
100e0 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
100f0 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
10100 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
10110 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
10120 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
10130 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
10140 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
10150 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
10160 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
10170 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
10180 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
10190 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
101a0 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
101b0 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
101c0 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
101d0 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
101e0 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
101f0 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
10200 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
10210 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
10220 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
10230 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
10240 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
10250 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
10260 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
10270 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
10280 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
10290 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
102a0 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
102b0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
102c0 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
102d0 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
102e0 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
102f0 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
10300 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
10310 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10320 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
10330 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
10340 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
10350 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
10360 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
10370 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10390 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
103a0 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
103b0 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
103c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
103d0 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
103e0 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
103f0 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
10400 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
10410 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10420 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
10430 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
10440 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
10450 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10460 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
10470 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
10480 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
10490 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
104a0 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
104b0 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
104c0 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
104d0 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
104e0 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
104f0 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
10500 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
10510 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
10520 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
10530 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
10540 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
10550 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
10560 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
10570 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
10580 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
10590 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
105a0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
105b0 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
105c0 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
105d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
105e0 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
105f0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
10600 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
10610 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
10620 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10630 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
10640 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
10650 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
10660 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
10670 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
10680 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
10690 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
106a0 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
106b0 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
106c0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
106d0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
106e0 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
106f0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10700 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
10710 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
10720 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
10730 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
10740 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
10750 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10760 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10770 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
10780 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
10790 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
107a0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
107b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
107c0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
107d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
107e0 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
107f0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10800 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10810 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
10820 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
10830 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
10840 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
10850 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
10860 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
10870 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
10880 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
10890 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
108a0 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
108b0 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
108c0 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
108d0 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
108e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
108f0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10900 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
10910 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10920 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10930 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
10940 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
10950 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
10960 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
10970 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
10980 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
10990 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
109a0 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
109b0 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
109c0 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
109d0 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
109e0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
109f0 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
10a00 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
10a10 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
10a20 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
10a30 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
10a40 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10a50 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
10a60 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10a70 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
10a80 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
10a90 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
10aa0 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
10ab0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
10ac0 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
10ad0 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
10ae0 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
10af0 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
10b00 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
10b10 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10b20 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
10b30 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
10b40 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
10b50 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10b60 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
10b70 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
10b80 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
10b90 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
10ba0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
10bb0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10bc0 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
10bd0 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10be0 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
10bf0 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
10c00 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10c10 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
10c20 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
10c30 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
10c40 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
10c50 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
10c60 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
10c70 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
10c80 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10c90 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
10ca0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10cb0 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
10cc0 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
10cd0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10ce0 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
10cf0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10d00 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
10d10 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
10d20 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
10d30 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
10d40 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
10d50 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
10d60 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
10d70 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
10d80 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
10d90 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
10da0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10db0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
10dc0 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
10dd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
10de0 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
10df0 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
10e00 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
10e10 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
10e20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
10e30 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
10e40 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10e50 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
10e60 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10e70 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
10e80 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
10e90 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10ea0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10eb0 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
10ec0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10ed0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10ee0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
10ef0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
10f00 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
10f10 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
10f20 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
10f30 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
10f40 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
10f50 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
10f60 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
10f70 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
10f80 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
10f90 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
10fa0 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
10fb0 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
10fc0 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
10fd0 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
10fe0 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
10ff0 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
11000 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
11010 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
11020 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
11030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11040 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
11050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11060 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
11070 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
11080 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
11090 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
110a0 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
110b0 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
110c0 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
110d0 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
110e0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
110f0 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
11100 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
11110 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
11120 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
11130 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
11140 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
11150 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
11160 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
11170 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
11180 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
11190 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
111a0 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
111b0 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
111c0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
111d0 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
111e0 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
111f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
11200 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
11210 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
11220 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
11230 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
11240 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
11250 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
11260 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
11270 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
11280 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
11290 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
112a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
112b0 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
112c0 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
112d0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
112e0 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
112f0 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
11300 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
11310 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
11320 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
11330 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
11340 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
11350 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
11360 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
11370 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11380 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
11390 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
113a0 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
113b0 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
113c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
113d0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
113e0 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
113f0 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
11400 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
11410 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
11420 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11430 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
11440 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
11450 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11460 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
11470 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
11480 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
11490 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
114a0 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
114b0 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
114c0 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
114d0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
114e0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
114f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11500 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
11510 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
11520 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
11530 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
11540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11550 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
11560 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11570 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
11580 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
11590 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
115a0 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
115b0 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
115c0 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
115d0 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
115e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
115f0 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
11600 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
11610 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11620 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
11630 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
11640 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
11650 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
11660 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
11670 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
11680 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
11690 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
116a0 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
116b0 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
116c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
116d0 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
116e0 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
116f0 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
11700 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
11710 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
11720 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
11730 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11740 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
11750 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
11760 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11770 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
11780 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11790 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
117a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
117b0 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
117c0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
117d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
117e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
117f0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
11800 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
11810 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
11820 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
11830 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
11840 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
11850 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
11860 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
11870 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
11880 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11890 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
118a0 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
118b0 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
118c0 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
118d0 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
118e0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
118f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11900 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11910 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
11920 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
11930 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
11940 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
11950 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
11960 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
11970 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
11980 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
11990 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
119a0 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
119b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
119c0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
119d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119e0 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
119f0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
11a00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
11a10 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
11a20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
11a30 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
11a40 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
11a50 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
11a60 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
11a70 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
11a80 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
11a90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
11aa0 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
11ab0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
11ac0 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
11ad0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
11ae0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
11af0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
11b00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
11b10 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
11b20 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11b30 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
11b40 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
11b50 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11b60 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
11b70 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
11b80 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
11b90 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
11ba0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
11bb0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11bc0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
11bd0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
11be0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11bf0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11c00 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
11c10 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
11c20 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
11c30 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
11c40 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
11c50 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
11c60 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11c70 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
11c80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11c90 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
11ca0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
11cb0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
11cc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
11cd0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
11ce0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11cf0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
11d00 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
11d10 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
11d20 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11d30 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11d40 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
11d50 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
11d60 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
11d70 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
11d80 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
11d90 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
11da0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
11db0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
11dc0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
11dd0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
11de0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
11df0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
11e00 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
11e10 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
11e20 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
11e30 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
11e40 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
11e50 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
11e60 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
11e70 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
11e80 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
11e90 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11ea0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
11eb0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
11ec0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11ed0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
11ee0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
11ef0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11f00 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
11f10 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
11f20 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
11f30 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11f40 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
11f50 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
11f60 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
11f70 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
11f80 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
11f90 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
11fa0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11fb0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
11fc0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11fd0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
11fe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
11ff0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
12000 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
12010 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
12020 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
12030 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
12040 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
12050 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
12060 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
12070 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
12080 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
12090 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
120a0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
120b0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
120c0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
120d0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
120e0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
120f0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
12100 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
12110 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12120 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
12130 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
12140 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
12150 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
12160 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
12170 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
12180 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
12190 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
121a0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
121b0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
121c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
121d0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
121e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
121f0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
12200 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
12210 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
12220 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12230 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
12240 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
12250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12260 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
12270 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
12280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12290 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
122a0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
122b0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
122c0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
122d0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
122e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
122f0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
12300 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
12310 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
12320 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
12330 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
12340 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
12350 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
12360 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
12370 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
12380 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
12390 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
123a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
123b0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
123c0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
123d0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
123e0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
123f0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12400 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
12410 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
12420 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
12430 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
12440 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12450 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
12460 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
12470 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
12480 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
12490 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
124a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
124b0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
124c0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
124d0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
124e0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
124f0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
12500 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
12510 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
12520 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
12530 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12540 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
12550 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
12560 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
12570 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
12580 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
12590 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
125a0 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
125b0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
125c0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
125d0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
125e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
125f0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
12600 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
12610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12620 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12630 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
12640 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
12650 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12660 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
12680 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
12690 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
126a0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
126b0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
126c0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
126d0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
126e0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
126f0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
12700 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
12710 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
12720 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
12730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12740 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
12750 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12760 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
12770 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
12780 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
12790 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
127a0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
127b0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
127c0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
127d0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
127e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
127f0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
12800 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
12810 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
12820 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
12830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12840 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
12850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
12860 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
12870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12880 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
12890 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
128a0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
128b0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
128c0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
128d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
128e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
128f0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
12900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12910 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
12920 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
12930 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
12940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12950 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
12960 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12970 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
12980 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12990 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
129a0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
129b0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
129c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
129d0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
129e0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
129f0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
12a00 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
12a10 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
12a20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
12a30 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
12a40 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
12a50 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
12a60 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
12a70 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
12a80 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
12a90 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
12aa0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12ab0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
12ac0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
12ad0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
12ae0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
12af0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
12b00 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12b10 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
12b20 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
12b30 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
12b40 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
12b50 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
12b60 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
12b70 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
12b80 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
12b90 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
12ba0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
12bb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12bc0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
12bd0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
12be0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
12bf0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
12c00 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
12c10 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
12c20 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12c30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
12c40 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
12c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12c60 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
12c70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12c80 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
12c90 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
12ca0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12cb0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
12cc0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
12cd0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
12ce0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
12cf0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
12d00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
12d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12d20 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
12d30 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
12d40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
12d50 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
12d60 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
12d80 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
12d90 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
12da0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
12db0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
12dc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
12dd0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
12de0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
12df0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
12e00 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
12e10 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
12e20 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
12e30 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
12e40 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
12e50 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
12e60 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
12e70 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
12e80 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
12e90 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12ea0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
12eb0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
12ec0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
12ed0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
12ee0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
12ef0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
12f00 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
12f10 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
12f20 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
12f30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12f40 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
12f50 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
12f60 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
12f70 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
12f80 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
12f90 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
12fa0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
12fb0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
12fc0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
12fd0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
12fe0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
12ff0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
13000 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
13010 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
13020 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
13030 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
13040 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
13050 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
13060 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
13070 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
13080 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
13090 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
130a0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
130b0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
130c0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
130d0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
130e0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
130f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13100 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
13110 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
13120 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
13130 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
13140 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
13150 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
13160 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
13170 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
13180 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
13190 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
131a0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
131b0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
131c0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
131d0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
131e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
131f0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
13200 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
13210 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
13220 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
13230 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
13240 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
13250 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
13260 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
13270 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
13280 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
13290 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
132a0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
132b0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
132c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
132d0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
132e0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
132f0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
13300 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13310 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
13320 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
13330 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
13340 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
13350 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
13360 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
13370 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
13380 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
13390 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
133a0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
133b0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
133c0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
133d0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
133e0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
133f0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
13400 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
13410 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
13420 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
13430 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
13440 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
13450 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
13460 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
13470 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
13480 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
13490 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
134a0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
134b0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
134c0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
134d0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
134e0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
134f0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
13500 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
13510 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
13520 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
13530 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
13540 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
13550 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
13560 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
13570 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
13580 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
13590 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
135a0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
135b0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
135c0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
135d0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
135e0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
135f0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
13600 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
13610 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
13620 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
13630 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
13640 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
13650 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
13660 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13670 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
13680 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
13690 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
136a0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
136b0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
136c0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
136d0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
136e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
136f0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
13700 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
13710 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
13720 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
13730 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
13740 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
13750 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
13760 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
13770 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
13780 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
13790 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
137a0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
137b0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
137c0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
137d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
137e0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
137f0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
13800 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
13810 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
13820 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
13830 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
13840 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
13850 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
13860 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
13870 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
13880 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
13890 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
138a0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
138b0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
138c0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
138d0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
138e0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
138f0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
13900 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
13910 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
13920 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13930 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
13940 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
13950 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
13960 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
13970 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
13980 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
13990 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
139a0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
139b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
139c0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
139d0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
139e0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
139f0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
13a00 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
13a10 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
13a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
13a30 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
13a40 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
13a50 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
13a60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
13a70 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
13a80 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
13a90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13aa0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
13ab0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
13ac0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
13ad0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
13ae0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
13af0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
13b00 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
13b10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
13b20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13b30 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
13b40 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
13b50 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
13b60 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
13b70 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
13b80 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
13b90 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
13ba0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
13bb0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
13bc0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
13bd0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
13be0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
13bf0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
13c00 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
13c10 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
13c20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
13c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13c40 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
13c50 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
13c60 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
13c70 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
13c80 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
13c90 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
13ca0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
13cb0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
13cc0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
13cd0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13ce0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
13cf0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13d00 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
13d10 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13d20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13d30 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
13d40 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13d50 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
13d60 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
13d70 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
13d80 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
13d90 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
13da0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
13db0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
13dc0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
13dd0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
13de0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
13df0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13e00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13e10 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13e20 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13e30 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13e40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13e50 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
13e60 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
13e70 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
13e80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
13e90 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
13ea0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
13eb0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
13ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13ed0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
13ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13ef0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
13f00 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13f10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
13f20 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13f30 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13f50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
13f60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f70 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
13f80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13f90 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13fa0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13fb0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13fc0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13fd0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13fe0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
13ff0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
14000 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
14010 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
14020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14030 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14040 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
14050 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
14060 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
14070 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
14080 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
14090 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
140a0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
140b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
140c0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
140d0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
140e0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
140f0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
14100 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
14110 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
14120 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
14130 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
14140 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
14150 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
14160 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14170 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
14180 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
14190 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
141a0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
141b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
141c0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
141d0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
141e0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
141f0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
14200 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
14210 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
14220 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
14230 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
14240 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
14250 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14260 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
14270 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
14280 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14290 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
142a0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
142b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
142c0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
142d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
142e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
142f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
14300 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
14310 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
14320 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
14330 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
14340 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
14350 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
14360 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
14370 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
14380 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
14390 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
143a0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
143b0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
143c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
143d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
143e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
143f0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
14400 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
14410 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
14420 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14430 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
14440 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
14450 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
14460 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
14470 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
14480 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14490 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
144a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
144b0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
144c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
144d0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
144e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
144f0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
14500 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
14510 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
14520 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
14530 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
14540 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
14550 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14560 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14570 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14580 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14590 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
145a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
145b0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
145c0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
145d0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
145e0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
145f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14600 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14610 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
14620 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
14630 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
14640 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
14650 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14660 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14670 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14680 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
14690 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
146a0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
146b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
146c0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
146d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
146e0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
146f0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
14700 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14710 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14720 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
14730 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14740 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14750 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
14760 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
14770 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
14780 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
14790 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
147a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
147b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
147c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
147d0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
147e0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
147f0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
14800 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
14810 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14820 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
14830 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
14840 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14850 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
14860 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14870 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14880 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
14890 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
148a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
148b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
148c0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
148d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
148e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
148f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14900 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14910 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14920 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
14930 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
14940 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14950 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14960 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14970 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14980 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
14990 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
149a0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
149b0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
149c0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
149d0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
149e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
149f0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14a00 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
14a10 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
14a20 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
14a30 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
14a40 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
14a50 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
14a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a70 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
14a80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14a90 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
14aa0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
14ab0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ac0 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f  G_SMALL_MALLOC o
14ad0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
14ae0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a  le argument of.*
14af0 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  * type int, inte
14b00 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14b10 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20 74  lean, which if t
14b20 72 75 65 20 70 72 6f 76 69 64 65 73 20 61 20 68  rue provides a h
14b30 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  int to.** SQLite
14b40 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20   that it should 
14b50 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f  avoid large memo
14b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69  ry allocations i
14b70 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53  f possible..** S
14b80 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20 66  QLite will run f
14b90 61 73 74 65 72 20 69 66 20 69 74 20 69 73 20 66  aster if it is f
14ba0 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67  ree to make larg
14bb0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14bc0 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d  ions,.** but som
14bd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
14be0 67 68 74 20 70 72 65 66 65 72 20 74 6f 20 72 75  ght prefer to ru
14bf0 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63 68  n slower in exch
14c00 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72  ange for.** guar
14c10 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65 6d  antees about mem
14c20 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  ory fragmentatio
14c30 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73 73 69  n that are possi
14c40 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20  ble if large.** 
14c50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20  allocations are 
14c60 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20 68  avoided.  This h
14c70 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  int is normally 
14c80 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  off..** </dd>.**
14c90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ca0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
14cb0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14cc0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
14cd0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14cf0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
14d00 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
14d10 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
14d20 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
14d30 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
14d40 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
14d50 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
14d60 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
14d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14d80 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
14d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14da0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
14db0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
14dc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
14dd0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
14de0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
14df0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
14e00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
14e10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
14e20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14e30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
14e40 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
14e50 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
14e60 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
14e70 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14e80 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
14e90 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
14ea0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
14eb0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14ec0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
14ed0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
14ee0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
14ef0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
14f00 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
14f10 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
14f20 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
14f30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14f40 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
14f50 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
14f60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14f70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14f80 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
14f90 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
14fa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
14fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14fc0 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73 20  RATCH option is 
14fd0 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a  no longer used..
14fe0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14ff0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15000 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
15010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15020 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
15030 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
15040 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15050 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15060 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
15070 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
15080 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
15090 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
150a0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
150b0 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
150c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
150d0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
150e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
150f0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
15100 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
15110 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
15120 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15130 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
15140 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
15150 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
15160 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
15170 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
15180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15190 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
151a0 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
151b0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
151c0 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
151d0 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
151e0 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
151f0 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
15200 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
15210 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
15220 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
15230 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
15240 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
15250 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
15260 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
15270 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
15280 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
15290 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
152a0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
152b0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
152c0 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
152d0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
152e0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
152f0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
15300 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15310 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
15320 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
15330 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
15340 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
15350 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
15360 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
15370 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
15380 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
15390 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
153a0 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
153b0 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
153c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
153d0 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
153e0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
153f0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
15400 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
15410 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
15420 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
15430 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
15440 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
15450 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
15460 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
15470 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
15480 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
15490 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
154a0 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
154b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
154c0 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
154d0 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
154e0 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
154f0 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
15500 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
15510 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
15520 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
15530 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
15540 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
15550 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15560 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
15570 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
15580 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
15590 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
155a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
155b0 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
155c0 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
155d0 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
155e0 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
155f0 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
15600 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
15610 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
15620 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
15630 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
15640 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
15650 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
15660 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
15670 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
15680 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
15690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
156a0 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
156b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
156c0 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
156d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
156e0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
156f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15700 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
15710 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
15720 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
15730 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
15740 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
15750 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
15760 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
15770 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
15780 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
15790 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
157a0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
157b0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
157d0 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  HE]..** ^The SQL
157e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
157f0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15800 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
15810 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  te is compiled.*
15820 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53  * with either [S
15830 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
15840 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45  SYS3] or [SQLITE
15850 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
15860 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
15870 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
15880 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77  f invoked otherw
15890 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ise..** ^There a
158a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
158b0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
158c0 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20  FIG_HEAP:.** An 
158d0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
158e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
158f0 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
15900 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
15910 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
15920 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
15930 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
15940 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
15950 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
15960 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
15970 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
15980 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
15990 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
159a0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
159b0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
159c0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
159d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
159e0 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
159f0 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
15a00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15a10 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
15a20 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
15a30 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
15a40 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
15a50 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
15a60 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
15a70 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
15a80 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
15a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
15aa0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
15ab0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
15ac0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
15ad0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
15ae0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
15af0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
15b00 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
15b10 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
15b20 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
15b30 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
15b40 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
15b50 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
15b60 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
15b70 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
15b80 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15b90 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
15ba0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
15bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15bc0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
15bd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15be0 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
15bf0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
15c00 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70  _CONFIG_MUTEX op
15c10 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15c20 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15c30 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  ch is a.** point
15c40 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
15c50 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
15c60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
15c70 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
15c80 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
15c90 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76  ifies alternativ
15ca0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
15cb0 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
15cc0 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63   used.** in plac
15cd0 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  e the mutex rout
15ce0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
15cf0 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
15d00 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15d10 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
15d20 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
15d30 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
15d40 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
15d50 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
15d60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15d70 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
15d80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15d90 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15da0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15db0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15dc0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15dd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15de0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
15df0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
15e00 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
15e10 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
15e20 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
15e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
15e40 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
15e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15e60 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
15e70 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
15e80 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15e90 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
15ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15eb0 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
15ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15ed0 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
15ee0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15ef0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15f00 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
15f10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15f20 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
15f30 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15f40 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
15f50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15f60 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
15f70 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
15f80 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
15f90 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
15fa0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
15fb0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15fc0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
15fd0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
15fe0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
15ff0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
16000 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
16010 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
16020 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
16030 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
16040 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
16050 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
16060 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
16070 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
16080 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
16090 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
160a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
160b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
160c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
160d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
160e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
160f0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
16100 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
16110 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
16120 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
16130 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
16140 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
16150 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
16160 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
16170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16180 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
16190 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
161a0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
161b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
161c0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
161d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
161e0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
161f0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
16200 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16210 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  E option takes t
16220 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
16230 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74  t determine.** t
16240 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20  he default size 
16250 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
16260 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74  ory on each [dat
16270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16280 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  ]..** The first 
16290 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
162a0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
162b0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
162c0 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
162d0 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
162e0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
162f0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
16300 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16310 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54  tion.)^  ^(SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16330 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c  DE.** sets the <
16340 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
16350 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
16360 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
16370 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
16380 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69   option to [sqli
16390 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
163a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
163b0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
163c0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
163d0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
163e0 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
163f0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
16400 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16410 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
16420 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16430 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
16440 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16450 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
16460 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16470 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
16480 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
16490 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
164a0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
164b0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
164c0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
164d0 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63  .** the interfac
164e0 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  e to a custom pa
164f0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
16500 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53  ntation.)^.** ^S
16510 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
16520 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
16530 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16540 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e  s2] object.</dd>
16550 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16560 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16570 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
16580 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
16590 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
165a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
165b0 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74  G_GETPCACHE2 opt
165c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
165d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
165e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
165f0 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
16600 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16610 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
16620 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74  e copies of.** t
16630 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20  he current page 
16640 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
16650 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
16660 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
16670 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16680 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
16690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
166a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
166b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
166c0 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
166d0 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
166e0 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
166f0 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
16700 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
16710 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
16720 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
16730 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
16740 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
16750 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
16760 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
16770 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
16780 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
16790 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
167a0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
167b0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
167c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
167d0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
167e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
167f0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
16800 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
16810 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
16820 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
16830 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
16840 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
16850 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
16860 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
16870 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
16880 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
16890 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
168a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
168b0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
168c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
168d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
168e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
168f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
16900 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
16910 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
16920 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
16930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16940 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
16950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
16960 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
16970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
169a0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
169b0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
169c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
169d0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
169e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
169f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
16a00 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
16a10 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
16a20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
16a30 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
16a40 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
16a50 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
16a60 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
16a70 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
16a80 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
16a90 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
16aa0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
16ab0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
16ac0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
16ad0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
16ae0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
16af0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
16b00 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
16b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
16b20 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
16b30 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
16b40 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
16b50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16b60 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
16b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
16b80 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
16b90 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69  _CONFIG_URI opti
16ba0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16bb0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
16bc0 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f  pe int..** If no
16bd0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  n-zero, then URI
16be0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16bf0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
16c00 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
16c10 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  is zero,.** then
16c20 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16c30 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
16c40 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61  ed.)^ ^If URI ha
16c50 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16c60 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61  ly.** enabled, a
16c70 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73  ll filenames pas
16c80 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
16c90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
16ca0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a  3_open_v2()],.**
16cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
16cc0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
16cd0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
16ce0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
16cf0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
16d00 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
16d10 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
16d20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
16d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
16d40 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
16d50 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
16d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
16d70 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
16d80 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
16d90 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
16da0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
16db0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
16dc0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
16dd0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
16de0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
16df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16e00 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
16e10 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
16e20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16e30 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
16e40 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
16e50 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
16e60 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
16e70 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
16e80 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
16e90 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
16ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16eb0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
16ec0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
16ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16ee0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
16ef0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16f00 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16f10 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74  G_INDEX_SCAN opt
16f20 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16f30 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72  le integer.** ar
16f40 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
16f50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
16f60 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
16f70 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
16f80 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73  isable.** the us
16f90 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
16fa0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
16fb0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
16fc0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
16fd0 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  r..** ^The defau
16fe0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
16ff0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
17000 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
17010 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17020 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
17030 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
17040 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
17050 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17060 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
17070 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
17080 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
17090 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
170a0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
170b0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
170c0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
170d0 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
170e0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
170f0 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
17100 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
17110 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
17120 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
17130 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
17140 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
17150 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
17160 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
17170 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
17180 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
17190 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
171a0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
171b0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
171c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
171d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
171e0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
171f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17200 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
17210 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
17220 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
17230 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
17240 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
17250 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
17260 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
17270 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
17280 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
17290 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
172a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
172b0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
172c0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
172d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
172e0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
172f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17300 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
17310 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
17320 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
17330 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
17340 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
17350 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
17360 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
17370 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
17380 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
17390 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
173a0 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
173b0 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
173c0 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
173d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
173e0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
173f0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
17400 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
17410 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
17420 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
17430 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
17440 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
17450 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
17460 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
17470 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
17480 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
17490 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
174a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
174b0 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
174c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
174d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
174e0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
174f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
17500 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
17510 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
17520 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
17530 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
17540 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
17550 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
17560 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
17570 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
17580 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
17590 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
175a0 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
175b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
175c0 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
175d0 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
175e0 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
175f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
17600 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
17610 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
17620 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17640 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
17650 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
17660 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
17670 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
17680 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
17690 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
176a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
176b0 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
176c0 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
176d0 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
176e0 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
176f0 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
17700 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
17710 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17720 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17730 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17740 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
17750 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
17760 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
17770 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
17780 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
17790 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
177a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
177b0 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
177c0 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
177d0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
177e0 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
177f0 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
17800 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
17810 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
17820 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
17830 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
17840 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
17850 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
17860 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
17870 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
17880 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
17890 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
178a0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
178b0 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
178c0 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
178d0 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
178e0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
178f0 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  ize.** will be s
17900 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
17910 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73  d if necessary s
17920 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  o that it does n
17930 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ot exceed the.**
17940 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61   compile-time ma
17950 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20  ximum mmap size 
17960 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17970 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53  QLITE_MAX_MMAP_S
17980 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  IZE] compile-tim
17990 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  e option.)^.** ^
179a0 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65  If either argume
179b0 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  nt to this optio
179c0 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  n is negative, t
179d0 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e  hen that argumen
179e0 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20  t is.** changed 
179f0 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74  to its compile-t
17a00 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a  ime default..**.
17a10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17a20 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17a30 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
17a40 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17a50 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  EAPSIZE.** <dd>^
17a60 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17a70 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17a80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
17a90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
17aa0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
17ab0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77  ed for Windows w
17ac0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
17ad0 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72  WIN32_MALLOC] pr
17ae0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
17af0 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53  o.** defined. ^S
17b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17b10 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65  32_HEAPSIZE take
17b20 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  s a 32-bit unsig
17b30 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ned integer valu
17b40 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66  e.** that specif
17b50 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ies the maximum 
17b60 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61  size of the crea
17b70 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20  ted heap..**.** 
17b80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17b90 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a  PCACHE_HDRSZ]].*
17ba0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17bb0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17bc0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17be0 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74  E_HDRSZ option t
17bf0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
17c00 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
17c10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17c20 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
17c30 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74  writes into that
17c40 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d   integer the num
17c50 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20  ber of extra.** 
17c60 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72  bytes per page r
17c70 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68  equired for each
17c80 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45   page in [SQLITE
17c90 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
17ca0 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e  E]..** The amoun
17cb0 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65  t of extra space
17cc0 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68   required can ch
17cd0 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f  ange depending o
17ce0 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a  n the compiler,.
17cf0 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f  ** target platfo
17d00 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76  rm, and SQLite v
17d10 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  ersion..**.** [[
17d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17d30 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ASZ]].** <dt>SQL
17d40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17d50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17d60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17d70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17d80 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17d90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20   which.** is an 
17da0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
17db0 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d   and sets the "M
17dc0 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22  inimum PMA Size"
17dd0 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68   for the multith
17de0 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72  readed.** sorter
17df0 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72   to that integer
17e00 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d  .  The default m
17e10 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20  inimum PMA Size 
17e20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  is set by the.**
17e30 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f   [SQLITE_SORTER_
17e40 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74  PMASZ] compile-t
17e50 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77  ime option.  New
17e60 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75   threads are lau
17e70 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70  nched.** to help
17e80 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61   with sort opera
17e90 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69  tions when multi
17ea0 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67  threaded sorting
17eb0 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28  .** is enabled (
17ec0 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  using the [PRAGM
17ed0 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61  A threads] comma
17ee0 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75  nd) and the amou
17ef0 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a  nt of content.**
17f00 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78   to be sorted ex
17f10 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73  ceeds the page s
17f20 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69  ize times the mi
17f30 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20  nimum of the.** 
17f40 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69  [PRAGMA cache_si
17f50 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20  ze] setting and 
17f60 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  this value..**.*
17f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17f80 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17f90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17fa0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17fb0 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54  _SPILL.** <dd>^T
17fc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17fd0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20  _STMTJRNL_SPILL 
17fe0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17ff0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
18000 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73  which.** becomes
18010 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20   the [statement 
18020 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74  journal] spill-t
18030 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64  o-disk threshold
18040 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e  .  .** [Statemen
18050 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20  t journals] are 
18060 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75  held in memory u
18070 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20  ntil their size 
18080 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78  (in bytes).** ex
18090 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73  ceeds this thres
180a0 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70  hold, at which p
180b0 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72  oint they are wr
180c0 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a  itten to disk..*
180d0 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65  * Or if the thre
180e0 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61  shold is -1, sta
180f0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
18100 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a  are always held.
18110 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69  ** exclusively i
18120 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e  n memory..** Sin
18130 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e  ce many statemen
18140 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72  t journals never
18150 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73   become large, s
18160 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c  etting the spill
18170 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f  .** threshold to
18180 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73   a value such as
18190 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74   64KiB can great
181a0 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d  ly reduce the am
181b0 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72  ount of.** I/O r
181c0 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f  equired to suppo
181d0 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c  rt statement rol
181e0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65  lback..** The de
181f0 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
18200 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
18210 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68  controlled by th
18220 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d  e.** [SQLITE_STM
18230 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d  TJRNL_SPILL] com
18240 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18250 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
18260 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
18270 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  F_SIZE]].** <dt>
18280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18290 52 54 45 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20  RTERREF_SIZE.** 
182a0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 43  <dd>The SQLITE_C
182b0 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f  ONFIG_SORTERREF_
182c0 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63 63 65  SIZE option acce
182d0 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  pts a single par
182e0 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70  ameter.** of typ
182f0 65 20 28 69 6e 74 29 20 2d 20 74 68 65 20 6e 65  e (int) - the ne
18300 77 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 73  w value of the s
18310 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20  orter-reference 
18320 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a  size threshold..
18330 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  ** Usually, when
18340 20 53 51 4c 69 74 65 20 75 73 65 73 20 61 6e 20   SQLite uses an 
18350 65 78 74 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f  external sort to
18360 20 6f 72 64 65 72 20 72 65 63 6f 72 64 73 20 61   order records a
18370 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61  ccording.** to a
18380 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  n ORDER BY claus
18390 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73 20 72 65  e, all fields re
183a0 71 75 69 72 65 64 20 62 79 20 74 68 65 20 63 61  quired by the ca
183b0 6c 6c 65 72 20 61 72 65 20 70 72 65 73 65 6e 74  ller are present
183c0 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65   in the.** sorte
183d0 64 20 72 65 63 6f 72 64 73 2e 20 48 6f 77 65 76  d records. Howev
183e0 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 64 65  er, if SQLite de
183f0 74 65 72 6d 69 6e 65 73 20 62 61 73 65 64 20 6f  termines based o
18400 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
18410 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c  ype.** of a tabl
18420 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74  e column that it
18430 73 20 76 61 6c 75 65 73 20 61 72 65 20 6c 69 6b  s values are lik
18440 65 6c 79 20 74 6f 20 62 65 20 76 65 72 79 20 6c  ely to be very l
18450 61 72 67 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a  arge - larger.**
18460 20 74 68 61 6e 20 74 68 65 20 63 6f 6e 66 69 67   than the config
18470 75 72 65 64 20 73 6f 72 74 65 72 2d 72 65 66 65  ured sorter-refe
18480 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72 65 73  rence size thres
18490 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61 20 72 65  hold - then a re
184a0 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74  ference.** is st
184b0 6f 72 65 64 20 69 6e 20 65 61 63 68 20 73 6f 72  ored in each sor
184c0 74 65 64 20 72 65 63 6f 72 64 20 61 6e 64 20 74  ted record and t
184d0 68 65 20 72 65 71 75 69 72 65 64 20 63 6f 6c 75  he required colu
184e0 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61 64 65 64  mn values loaded
184f0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 64 61 74  .** from the dat
18500 61 62 61 73 65 20 61 73 20 72 65 63 6f 72 64 73  abase as records
18510 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 69 6e   are returned in
18520 20 73 6f 72 74 65 64 20 6f 72 64 65 72 2e 20 54   sorted order. T
18530 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  he default.** va
18540 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
18550 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76 65 72 20  ion is to never 
18560 75 73 65 20 74 68 69 73 20 6f 70 74 69 6d 69 7a  use this optimiz
18570 61 74 69 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e  ation. Specifyin
18580 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65  g a .** negative
18590 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
185a0 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72 65 73 20  option restores 
185b0 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  the default beha
185c0 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f  viour..** This o
185d0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
185e0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
185f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
18600 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
18610 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f  E_ENABLE_SORTER_
18620 52 45 46 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70  REFERENCES] comp
18630 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
18640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
18650 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58  CONFIG_MEMDB_MAX
18660 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
18670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44  LITE_CONFIG_MEMD
18680 42 5f 4d 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64  B_MAXSIZE.** <dd
18690 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
186a0 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
186b0 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20   option accepts 
186c0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
186d0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  er.** [sqlite3_i
186e0 6e 74 36 34 5d 20 70 61 72 61 6d 65 74 65 72 20  nt64] parameter 
186f0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
18700 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a  ault maximum siz
18710 65 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f  e for an in-memo
18720 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ry.** database c
18730 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
18740 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a  lite3_deserializ
18750 65 28 29 5d 2e 20 20 54 68 69 73 20 64 65 66 61  e()].  This defa
18760 75 6c 74 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73  ult maximum.** s
18770 69 7a 65 20 63 61 6e 20 62 65 20 61 64 6a 75 73  ize can be adjus
18780 74 65 64 20 75 70 20 6f 72 20 64 6f 77 6e 20 66  ted up or down f
18790 6f 72 20 69 6e 64 69 76 69 64 75 61 6c 20 64 61  or individual da
187a0 74 61 62 61 73 65 73 20 75 73 69 6e 67 20 74 68  tabases using th
187b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
187c0 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b  TL_SIZE_LIMIT] [
187d0 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
187e0 74 72 6f 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f  trol|file-contro
187f0 6c 5d 2e 20 20 49 66 20 74 68 69 73 0a 2a 2a 20  l].  If this.** 
18800 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 65  configuration se
18810 74 74 69 6e 67 20 69 73 20 6e 65 76 65 72 20 75  tting is never u
18820 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 65  sed, then the de
18830 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73  fault maximum is
18840 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
18850 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45  y the [SQLITE_ME
18860 4d 44 42 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53  MDB_DEFAULT_MAXS
18870 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  IZE] compile-tim
18880 65 20 6f 70 74 69 6f 6e 2e 20 20 49 66 20 74 68  e option.  If th
18890 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  at.** compile-ti
188a0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74  me option is not
188b0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
188c0 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69  efault maximum i
188d0 73 20 31 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a  s 1073741824..**
188e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
188f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18900 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
18910 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
18920 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18930 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
18940 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
18950 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18960 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
18970 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
18980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18990 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
189a0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
189b0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
189c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
189d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
189e0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
189f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
18a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
18a20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f       6  /* No lo
18a30 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
18a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18a50 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
18a60 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
18a70 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
18a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18a90 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
18aa0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
18ab0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
18ac0 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
18ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
18ae0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
18af0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
18b00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18b10 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
18b20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
18b30 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
18b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18b50 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
18b60 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
18b70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
18b80 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
18b90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
18ba0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
18bb0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
18bc0 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
18bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18be0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
18bf0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18c00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18c10 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
18c20 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c40 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
18c50 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
18c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c70 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
18c80 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
18c90 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
18ca0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18cb0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
18cc0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18cd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18ce0 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
18cf0 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
18d00 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
18d10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d20 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
18d30 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
18d40 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
18d50 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
18d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
18d70 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
18d80 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
18d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18da0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
18db0 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
18dc0 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
18dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18de0 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
18df0 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
18e00 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
18e10 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
18e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
18e30 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
18e40 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
18e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e60 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18e70 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
18e80 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
18e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ea0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
18eb0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
18ec0 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
18ed0 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
18ee0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
18ef0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
18f00 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
18f10 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
18f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
18f30 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  L_MALLOC        
18f40 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a  27  /* boolean *
18f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18f60 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
18f70 46 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20  F_SIZE      28  
18f80 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
18f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18fa0 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53  ONFIG_MEMDB_MAXS
18fb0 49 5a 45 20 20 20 20 20 20 20 32 39 20 20 2f 2a  IZE       29  /*
18fc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18fd0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
18fe0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
18ff0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
19000 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
19010 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
19020 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
19030 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
19040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
19050 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
19060 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
19070 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19080 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
19090 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
190a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
190b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
190c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
190d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
190e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
190f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
19100 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19110 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
19120 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
19130 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
19140 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
19150 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
19160 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
19170 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
19180 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
19190 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
191a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
191b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
191c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
191d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
191e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
191f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
19200 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
19210 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
19220 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
19230 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
19240 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19250 4b 41 53 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  KASIDE]].** <dt>
19260 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19270 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
19280 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19290 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
192a0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
192b0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
192c0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
192d0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
192e0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
192f0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
19300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19310 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
19320 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
19330 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
19340 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
19350 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
19360 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
19370 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
19380 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
19390 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
193a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
193b0 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
193c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
193d0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
193e0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
193f0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
19400 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
19410 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
19420 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
19430 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
19440 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
19450 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19460 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
19470 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
19480 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
19490 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
194a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
194b0 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
194c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
194d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
194e0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
194f0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
19500 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
19510 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
19520 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
19530 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
19540 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
19550 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
19560 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
19570 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19580 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
19590 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
195a0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
195b0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
195c0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
195d0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
195e0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
195f0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
19600 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
19610 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
19620 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
19630 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
19640 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
19650 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
19660 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
19670 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
19680 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
19690 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
196a0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
196b0 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
196c0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
196d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
196e0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
196f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
19700 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
19710 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
19720 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
19730 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
19740 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
19750 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
19760 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
19770 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
19780 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
19790 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
197a0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
197b0 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
197c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
197d0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
197e0 4b 45 59 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  KEY]].** <dt>SQL
197f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19800 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
19810 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19820 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19830 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19840 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
19850 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
19860 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
19870 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
19880 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
19890 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
198a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
198b0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
198c0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
198d0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
198e0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
198f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
19900 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
19910 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19920 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
19930 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
19940 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19950 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19960 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
19970 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
19980 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19990 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
199a0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
199b0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
199c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
199d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
199e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
199f0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19a00 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19a10 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
19a20 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
19a30 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
19a40 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
19a50 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
19a60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
19a70 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  R]].** <dt>SQLIT
19a80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19a90 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
19aa0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19ab0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19ac0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
19ad0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
19ae0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
19af0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19b00 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19b10 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19b20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19b30 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19b40 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19b50 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
19b60 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19b70 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
19b80 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
19b90 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
19ba0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
19bb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19bc0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
19bd0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19be0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19bf0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19c00 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19c10 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
19c20 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
19c30 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
19c40 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19c50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19c60 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
19c70 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19c80 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
19c90 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
19ca0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19cb0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
19cc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19cd0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
19ce0 4e 49 5a 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  NIZER]].** <dt>S
19cf0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19d00 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
19d10 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZER</dt>.** <dd
19d20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19d30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19d40 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 0a   or disable the.
19d50 2a 2a 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ** [fts3_tokeniz
19d60 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
19d70 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
19d80 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
19d90 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
19da0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
19db0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19dc0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19dd0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19de0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19df0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19e00 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19e10 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
19e20 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
19e30 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19e40 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
19e50 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
19e60 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
19e70 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
19e80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19e90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19ea0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19eb0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19ec0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19ed0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19ee0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
19ef0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
19f00 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19f10 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19f20 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19f30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19f40 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19f50 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19f60 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
19f70 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19f80 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19f90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
19fa0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19fb0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d  LOAD_EXTENSION]]
19fc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19fd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
19fe0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
19ff0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
1a000 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
1a010 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
1a020 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
1a030 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
1a040 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1a050 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
1a060 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
1a070 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
1a080 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
1a090 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1a0a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a0b0 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
1a0c0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
1a0d0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
1a0e0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
1a0f0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
1a100 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
1a110 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
1a120 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
1a130 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a140 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
1a150 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
1a160 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
1a170 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
1a180 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
1a190 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
1a1a0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
1a1b0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
1a1c0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
1a1d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1a1e0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
1a1f0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
1a200 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
1a210 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a220 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
1a230 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
1a240 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
1a250 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
1a260 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
1a270 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
1a280 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
1a290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
1a2a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a2b0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a2c0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a2d0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
1a2e0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a2f0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a300 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
1a310 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a320 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
1a330 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
1a340 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
1a350 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
1a360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
1a370 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
1a380 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
1a390 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
1a3a0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
1a3b0 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
1a3c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a3d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1a3e0 49 4e 44 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53  INDBNAME]] <dt>S
1a3f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1a400 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a  AINDBNAME</dt>.*
1a410 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
1a420 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
1a430 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f  hange the name o
1a440 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74  f the "main" dat
1a450 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e  abase.** schema.
1a460 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75    ^The sole argu
1a470 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1a480 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20  r to a constant 
1a490 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77  UTF8 string.** w
1a4a0 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65  hich will become
1a4b0 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20   the new schema 
1a4c0 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  name in place of
1a4d0 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74   "main".  ^SQLit
1a4e0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61  e.** does not ma
1a4f0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
1a500 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61   new main schema
1a510 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f   name string, so
1a520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a530 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
1a540 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e  that the argumen
1a550 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  t passed into th
1a560 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69  is DBCONFIG opti
1a570 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a  on is unchanged.
1a580 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ** until after t
1a590 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a5a0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
1a5b0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1a5c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a5d0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
1a5e0 5d 5d 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  ]] .** <dt>SQLIT
1a5f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
1a600 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e  PT_ON_CLOSE</dt>
1a610 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79  .** <dd> Usually
1a620 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  , when a databas
1a630 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73  e in wal mode is
1a640 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63   closed or detac
1a650 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64  hed from a .** d
1a660 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20  atabase handle, 
1a670 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66  SQLite checks if
1a680 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20   this will mean 
1a690 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e  that there are n
1a6a0 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63  ow no .** connec
1a6b0 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20  tions at all to 
1a6c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66  the database. If
1a6d0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73   so, it performs
1a6e0 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a   a checkpoint .*
1a6f0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f  * operation befo
1a700 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63  re closing the c
1a710 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20  onnection. This 
1a720 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73  option may be us
1a730 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64  ed to.** overrid
1a740 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72  e this behaviour
1a750 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
1a760 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
1a770 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a  this operation.*
1a780 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
1a790 2d 20 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69  - positive to di
1a7a0 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74  sable checkpoint
1a7b0 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a  s-on-close, or z
1a7c0 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61  ero (the.** defa
1a7d0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74  ult) to enable t
1a7e0 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76  hem, and negativ
1a7f0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a800 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1a810 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a820 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a830 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a840 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69  eger.** into whi
1a850 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ch is written 0 
1a860 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a870 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f   whether checkpo
1a880 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a  ints-on-close.**
1a890 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62   have been disab
1a8a0 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20  led - 0 if they 
1a8b0 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64  are not disabled
1a8c0 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e  , 1 if they are.
1a8d0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a8e0 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1a8f0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20  G_ENABLE_QPSG]] 
1a900 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a910 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c  FIG_ENABLE_QPSG<
1a920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  /dt>.** <dd>^(Th
1a930 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1a940 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70  G_ENABLE_QPSG op
1a950 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
1a960 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a  r deactivates.**
1a970 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e   the [query plan
1a980 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67 75  ner stability gu
1a990 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e  arantee] (QPSG).
1a9a0 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47 20    When the QPSG 
1a9b0 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20  is active,.** a 
1a9c0 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79  single SQL query
1a9d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
1a9e0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
1a9f0 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65  ame algorithm re
1aa00 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76  gardless.** of v
1aa10 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20  alues of [bound 
1aa20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54  parameters].)^ T
1aa30 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65 73  he QPSG disables
1aa40 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69   some query opti
1aa50 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61  mizations.** tha
1aa60 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61  t look at the va
1aa70 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61  lues of bound pa
1aa80 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20  rameters, which 
1aa90 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75  can make some qu
1aaa0 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e  eries.** slower.
1aab0 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20 68    But the QPSG h
1aac0 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65  as the advantage
1aad0 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74   of more predict
1aae0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20  able behavior.  
1aaf0 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47  With.** the QPSG
1ab00 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20   active, SQLite 
1ab10 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20  will always use 
1ab20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 70  the same query p
1ab30 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64  lan in the field
1ab40 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20   as.** was used 
1ab50 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69  during testing i
1ab60 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68  n the lab..** Th
1ab70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ab80 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67   to this setting
1ab90 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1aba0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1abb0 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53  able .** the QPS
1abc0 47 2c 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  G, positive to e
1abd0 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e  nable QPSG, or n
1abe0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
1abf0 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
1ac00 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73  unchanged. The s
1ac10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1ac20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1ac30 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1ac40 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
1ac50 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1ac60 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
1ac70 68 65 20 51 50 53 47 20 69 73 20 64 69 73 61 62  he QPSG is disab
1ac80 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
1ac90 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
1aca0 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   call..** </dd>.
1acb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1acc0 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1acd0 45 51 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EQP]] <dt>SQLITE
1ace0 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45  _DBCONFIG_TRIGGE
1acf0 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  R_EQP</dt>.** <d
1ad00 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  d> By default, t
1ad10 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50  he output of EXP
1ad20 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20  LAIN QUERY PLAN 
1ad30 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f  commands does no
1ad40 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75  t .** include ou
1ad50 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65  tput for any ope
1ad60 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65  rations performe
1ad70 64 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f  d by trigger pro
1ad80 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f  grams. This.** o
1ad90 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1ada0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74   set or clear (t
1adb0 68 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c  he default) a fl
1adc0 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20  ag that governs 
1add0 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72  this.** behavior
1ade0 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
1adf0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
1ae00 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69  this operation i
1ae10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a  s an integer -.*
1ae20 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
1ae30 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20  able output for 
1ae40 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1ae50 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73  , or zero to dis
1ae60 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e  able it,.** or n
1ae70 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
1ae80 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
1ae90 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
1aea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1aeb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1aec0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1aed0 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
1aee0 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69   .** 0 or 1 to i
1aef0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1af00 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67  output-for-trigg
1af10 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73  ers has been dis
1af20 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a  abled - 0 if .**
1af30 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62   it is not disab
1af40 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e  led, 1 if it is.
1af50 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a    .** </dd>.**.*
1af60 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1af70 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1af80 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
1af90 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1afa0 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20  ATABASE</dt>.** 
1afb0 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c  <dd> Set the SQL
1afc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1afd0 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67  ET_DATABASE flag
1afe0 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a   and then run.**
1aff0 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64   [VACUUM] in ord
1b000 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64 61  er to reset a da
1b010 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61  tabase back to a
1b020 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73 65  n empty database
1b030 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65  .** with no sche
1b040 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e  ma and no conten
1b050 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  t. The following
1b060 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65   process works e
1b070 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64  ven for.** a bad
1b080 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61 74  ly corrupted dat
1b090 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c  abase file:.** <
1b0a0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74  ol>.** <li> If t
1b0b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b0c0 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20  ection is newly 
1b0d0 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72  opened, make sur
1b0e0 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74 68  e it has read th
1b0f0 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61  e.**      databa
1b100 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72 65  se schema by pre
1b110 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63  paring then disc
1b120 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72  arding some quer
1b130 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a  y against the.**
1b140 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c 20        database, 
1b150 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  or calling sqlit
1b160 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1b170 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f  metadata(), igno
1b180 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20  ring any.**     
1b190 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73   errors.  This s
1b1a0 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65  tep is only nece
1b1b0 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70 70  ssary if the app
1b1c0 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73  lication desires
1b1d0 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20   to keep.**     
1b1e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1b1f0 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20   WAL mode after 
1b200 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74 20  the reset if it 
1b210 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20  was in WAL mode 
1b220 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74  before.**      t
1b230 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c  he reset.  .** <
1b240 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1b250 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1b260 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1b270 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b  DATABASE, 1, 0);
1b280 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  .** <li> [sqlite
1b290 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41  3_exec](db, "[VA
1b2a0 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29  CUUM]", 0, 0, 0)
1b2b0 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ;.** <li> sqlite
1b2c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1b2d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b2e0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1b2f0 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  0, 0);.** </ol>.
1b300 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74  ** Because reset
1b310 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ting a database 
1b320 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61  is destructive a
1b330 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c  nd irreversible,
1b340 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20   the.** process 
1b350 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65  requires the use
1b360 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65   of this obscure
1b370 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c   API and multipl
1b380 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a  e steps to help.
1b390 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69  ** ensure that i
1b3a0 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65  t does not happe
1b3b0 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a  n by accident..*
1b3c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1b3d0 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45  CONFIG_DEFENSIVE
1b3e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b3f0 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45  CONFIG_DEFENSIVE
1b400 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b410 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b420 5f 44 45 46 45 4e 53 49 56 45 20 6f 70 74 69 6f  _DEFENSIVE optio
1b430 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1b440 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a  eactivates the.*
1b450 2a 20 22 64 65 66 65 6e 73 69 76 65 22 20 66 6c  * "defensive" fl
1b460 61 67 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ag for a databas
1b470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57  e connection.  W
1b480 68 65 6e 20 74 68 65 20 64 65 66 65 6e 73 69 76  hen the defensiv
1b490 65 0a 2a 2a 20 66 6c 61 67 20 69 73 20 65 6e 61  e.** flag is ena
1b4a0 62 6c 65 64 2c 20 6c 61 6e 67 75 61 67 65 20 66  bled, language f
1b4b0 65 61 74 75 72 65 73 20 74 68 61 74 20 61 6c 6c  eatures that all
1b4c0 6f 77 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20  ow ordinary SQL 
1b4d0 74 6f 20 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74  to .** deliberat
1b4e0 65 6c 79 20 63 6f 72 72 75 70 74 20 74 68 65 20  ely corrupt the 
1b4f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 72  database file ar
1b500 65 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  e disabled.  The
1b510 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61   disabled.** fea
1b520 74 75 72 65 73 20 69 6e 63 6c 75 64 65 20 62 75  tures include bu
1b530 74 20 61 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65  t are not limite
1b540 64 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  d to the followi
1b550 6e 67 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ng:.** <ul>.** <
1b560 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20  li> The [PRAGMA 
1b570 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d  writable_schema=
1b580 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  ON] statement..*
1b590 2a 20 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f  * <li> Writes to
1b5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70   the [sqlite_dbp
1b5b0 61 67 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62  age] virtual tab
1b5c0 6c 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65  le..** <li> Dire
1b5d0 63 74 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68  ct writes to [sh
1b5e0 61 64 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  adow tables]..**
1b5f0 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a   </ul>.** </dd>.
1b600 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1b610 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45  BCONFIG_WRITABLE
1b620 5f 53 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51  _SCHEMA]] <dt>SQ
1b630 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52  LITE_DBCONFIG_WR
1b640 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64  ITABLE_SCHEMA</d
1b650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
1b660 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52  LITE_DBCONFIG_WR
1b670 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70  ITABLE_SCHEMA op
1b680 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
1b690 72 20 64 65 61 63 74 69 76 61 74 65 73 20 74 68  r deactivates th
1b6a0 65 0a 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73  e.** "writable_s
1b6b0 63 68 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69  chema" flag. Thi
1b6c0 73 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  s has the same e
1b6d0 66 66 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67  ffect and is log
1b6e0 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e  ically equivalen
1b6f0 74 0a 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20  t.** to setting 
1b700 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65  [PRAGMA writable
1b710 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b  _schema=ON] or [
1b720 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f  PRAGMA writable_
1b730 73 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20  schema=OFF]..** 
1b740 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1b750 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74 69  nt to this setti
1b760 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ng is an integer
1b770 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1b780 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77  isable .** the w
1b790 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20  ritable_schema, 
1b7a0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1b7b0 6c 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65  le writable_sche
1b7c0 6d 61 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ma, or negative 
1b7d0 74 6f 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20  to.** leave the 
1b7e0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
1b7f0 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  d. The second pa
1b800 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1b810 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
1b820 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1b830 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1b840 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1b850 68 65 74 68 65 72 20 74 68 65 20 77 72 69 74 61  hether the writa
1b860 62 6c 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73  ble_schema.** is
1b870 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
1b880 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
1b890 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64  his call..** </d
1b8a0 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d>.** </dl>.*/.#
1b8b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b8c0 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d  CONFIG_MAINDBNAM
1b8d0 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30  E            100
1b8e0 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a  0 /* const char*
1b8f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b900 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
1b910 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20  ASIDE           
1b920 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20    1001 /* void* 
1b930 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
1b940 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b950 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
1b960 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a           1002 /*
1b970 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1b980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b990 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
1b9a0 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20  GER        1003 
1b9b0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b9c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b9d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
1b9e0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30  S3_TOKENIZER 100
1b9f0 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
1ba00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ba10 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1ba20 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31  LOAD_EXTENSION 1
1ba30 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  005 /* int int* 
1ba40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ba50 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
1ba60 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20  PT_ON_CLOSE     
1ba70 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74   1006 /* int int
1ba80 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1ba90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1baa0 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20  BLE_QPSG        
1bab0 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69     1007 /* int i
1bac0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1bad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54  QLITE_DBCONFIG_T
1bae0 52 49 47 47 45 52 5f 45 51 50 20 20 20 20 20 20  RIGGER_EQP      
1baf0 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74       1008 /* int
1bb00 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1bb10 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1bb20 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 20  _RESET_DATABASE 
1bb30 20 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69         1009 /* i
1bb40 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1bb50 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1bb60 49 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20  IG_DEFENSIVE    
1bb70 20 20 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a           1010 /*
1bb80 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1bb90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1bba0 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43  NFIG_WRITABLE_SC
1bbb0 48 45 4d 41 20 20 20 20 20 20 20 31 30 31 31 20  HEMA       1011 
1bbc0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1bbd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1bbe0 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20  CONFIG_MAX      
1bbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31               101
1bc00 31 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43  1 /* Largest DBC
1bc10 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ONFIG */../*.** 
1bc20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
1bc30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
1bc40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
1bc50 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1bc60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1bc70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1bc80 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
1bc90 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
1bca0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
1bcb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bcc0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
1bcd0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
1bce0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
1bcf0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
1bd00 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1bd10 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
1bd20 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
1bd30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bd40 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
1bd50 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
1bd60 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
1bd70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
1bd80 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
1bd90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1bda0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
1bdb0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
1bdc0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
1bdd0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
1bde0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
1bdf0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
1be00 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
1be10 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
1be20 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
1be30 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
1be40 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
1be50 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
1be60 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
1be70 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
1be80 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
1be90 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
1bea0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
1beb0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
1bec0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1bed0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
1bee0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
1bef0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
1bf00 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
1bf10 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
1bf20 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
1bf30 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
1bf40 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
1bf50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bf60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1bf70 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75  d(D) interface u
1bf80 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  sually returns t
1bf90 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a  he [rowid] of.**
1bfa0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1bfb0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1bfc0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
1bfd0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
1bfe0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
1bff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c000 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73  tion D. ^Inserts
1c010 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
1c020 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
1c030 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64   not.** recorded
1c040 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  . ^If no success
1c050 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
1c060 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
1c070 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
1c080 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61  ed .** on the da
1c090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c0a0 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  n D, then sqlite
1c0b0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c0c0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a  wid(D) returns .
1c0d0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41  ** zero..**.** A
1c0e0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20  s well as being 
1c0f0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  set automaticall
1c100 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e  y as rows are in
1c110 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61  serted into data
1c120 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20  base.** tables, 
1c130 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c140 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1c150 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65  ion may be set e
1c160 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20  xplicitly by.** 
1c170 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1c180 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1c190 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72  ].**.** Some vir
1c1a0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
1c1b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49  mentations may I
1c1c0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20  NSERT rows into 
1c1d0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a  rowid tables as.
1c1e0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69  ** part of commi
1c1f0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  tting a transact
1c200 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75  ion (e.g. to flu
1c210 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61  sh data accumula
1c220 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  ted in memory.**
1c230 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68   to disk). In th
1c240 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65  is case subseque
1c250 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73  nt calls to this
1c260 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1c270 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73   the rowid.** as
1c280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1c290 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53  ese internal INS
1c2a0 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20  ERT operations, 
1c2b0 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a  which leads to .
1c2c0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72  ** unintuitive r
1c2d0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20  esults. Virtual 
1c2e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1c2f0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72  tions that do wr
1c300 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20  ite to rowid.** 
1c310 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77  tables in this w
1c320 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69  ay can avoid thi
1c330 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73  s problem by res
1c340 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  toring the origi
1c350 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61  nal .** rowid va
1c360 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  lue using [sqlit
1c370 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1c380 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f  rt_rowid()] befo
1c390 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a  re returning .**
1c3a0 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20   control to the 
1c3b0 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  user..**.** ^(If
1c3c0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1c3d0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1c3e0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72  gger then this r
1c3f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20  outine will .** 
1c400 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
1c410 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
1c420 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ed row as long a
1c430 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
1c440 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e   .** running. On
1c450 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ce the trigger p
1c460 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65  rogram ends, the
1c470 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c480 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
1c490 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
1c4a0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
1c4b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61  e the trigger wa
1c4c0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  s fired.)^.**.**
1c4d0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
1c4e0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
1c4f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1c500 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
1c510 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
1c520 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
1c530 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1c540 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1c550 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1c560 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
1c570 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
1c580 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
1c590 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
1c5a0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
1c5b0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
1c5c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
1c5d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1c5e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
1c5f0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
1c600 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
1c610 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1c620 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
1c630 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1c640 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
1c650 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
1c660 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
1c670 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
1c680 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
1c690 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
1c6a0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
1c6b0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
1c6c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1c6d0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
1c6e0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
1c6f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1c700 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
1c710 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
1c720 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
1c730 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
1c740 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
1c750 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
1c760 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
1c770 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
1c780 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
1c790 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1c7a0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
1c7b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c7c0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
1c7d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
1c7e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1c7f0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1c800 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
1c810 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
1c820 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
1c830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c840 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
1c850 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1c860 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
1c870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1c880 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
1c890 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
1c8a0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
1c8b0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1c8c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1c8d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1c8e0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
1c8f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1c900 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
1c910 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
1c920 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
1c930 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1c940 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
1c950 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
1c960 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1c970 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1c980 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
1c990 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
1c9a0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
1c9b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c9c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1c9d0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1c9e0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
1c9f0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
1ca00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
1ca10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
1ca20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
1ca30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
1ca40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
1ca50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
1ca60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
1ca70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
1ca80 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  se..*/.void sqli
1ca90 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1caa0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
1cab0 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
1cac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cad0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
1cae0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1caf0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1cb00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1cb10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1cb20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1cb30 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1cb40 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
1cb50 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
1cb60 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1cb70 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
1cb80 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1cb90 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
1cba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1cbb0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
1cbc0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
1cbd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
1cbe0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1cbf0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1cc00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1cc10 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
1cc20 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
1cc30 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
1cc40 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
1cc50 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
1cc60 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
1cc70 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1cc80 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
1cc90 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
1cca0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
1ccb0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
1ccc0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1ccd0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
1cce0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1ccf0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
1cd00 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1cd10 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
1cd20 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
1cd30 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1cd40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1cd50 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
1cd60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1cd70 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
1cd80 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
1cd90 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
1cda0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
1cdb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1cdc0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
1cdd0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
1cde0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
1cdf0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1ce00 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
1ce10 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
1ce20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1ce30 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
1ce40 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
1ce50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
1ce60 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
1ce70 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
1ce80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1ce90 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
1cea0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
1ceb0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
1cec0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
1ced0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
1cee0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
1cef0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1cf00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
1cf10 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
1cf20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1cf30 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
1cf40 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
1cf50 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
1cf60 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
1cf70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
1cf80 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
1cf90 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
1cfa0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1cfb0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
1cfc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1cfd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
1cfe0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
1cff0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1d000 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1d010 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1d020 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1d030 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1d040 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1d050 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1d060 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1d070 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1d080 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1d090 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1d0a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d0b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1d0c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1d0d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1d0e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1d0f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1d100 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1d110 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1d120 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1d130 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1d140 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1d150 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1d160 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1d170 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1d180 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1d190 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1d1a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1d1b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1d1c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1d1d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1d1e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1d1f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1d200 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1d210 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1d220 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1d230 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1d240 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1d250 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1d260 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1d270 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1d280 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1d290 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1d2a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1d2b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1d2c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1d2d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1d2e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1d2f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1d300 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1d310 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1d320 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1d330 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1d340 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1d350 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1d360 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1d370 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1d380 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1d390 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1d3a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1d3b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1d3c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1d3d0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1d3e0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1d3f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1d400 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1d410 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1d420 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1d430 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
1d440 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  > the [sqlite3_t
1d450 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1d460 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69  interface.** <li
1d470 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61  > the [count_cha
1d480 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  nges pragma].** 
1d490 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65  <li> the [change
1d4a0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1d4b0 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64  ].** <li> the [d
1d4c0 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67  ata_version prag
1d4d0 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ma].** </ul>.*/.
1d4e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1d4f0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1d500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d510 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1d520 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1d530 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1d540 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1d550 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1d560 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1d570 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1d580 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1d590 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1d5a0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1d5b0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1d5c0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1d5d0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1d5e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d5f0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1d600 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1d610 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1d620 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1d630 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1d640 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1d650 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1d660 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1d670 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1d680 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1d690 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1d6a0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1d6b0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1d6c0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1d6d0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1d6e0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1d6f0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1d700 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1d710 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1d720 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1d730 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1d740 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1d750 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1d760 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1d770 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1d780 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1d790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ..**.** The [sql
1d7a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1d7b0 65 73 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  es(D)] interface
1d7c0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 74 68   only reports th
1d7d0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72  e number.** of r
1d7e0 6f 77 73 20 74 68 61 74 20 63 68 61 6e 67 65 64  ows that changed
1d7f0 20 64 75 65 20 74 6f 20 53 51 4c 20 73 74 61 74   due to SQL stat
1d800 65 6d 65 6e 74 20 72 75 6e 20 61 67 61 69 6e 73  ement run agains
1d810 74 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  t database.** co
1d820 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79  nnection D.  Any
1d830 20 63 68 61 6e 67 65 73 20 62 79 20 6f 74 68 65   changes by othe
1d840 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
1d850 63 74 69 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72  ctions are ignor
1d860 65 64 2e 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74  ed..** To detect
1d870 20 63 68 61 6e 67 65 73 20 61 67 61 69 6e 73 74   changes against
1d880 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1d890 20 66 72 6f 6d 20 6f 74 68 65 72 20 64 61 74 61   from other data
1d8a0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
1d8b0 6f 6e 73 20 75 73 65 20 74 68 65 20 5b 50 52 41  ons use the [PRA
1d8c0 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e  GMA data_version
1d8d0 5d 20 63 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65  ] command or the
1d8e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
1d8f0 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
1d900 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a  [file control]..
1d910 2a 2a 20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  ** .** If a sepa
1d920 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1d930 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1d940 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1d950 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1d960 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
1d970 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
1d980 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1d990 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1d9a0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
1d9b0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1d9c0 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  ingful..**.** Se
1d9d0 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a  e also:.** <ul>.
1d9e0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c  ** <li> the [sql
1d9f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1da00 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69  interface.** <li
1da10 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61  > the [count_cha
1da20 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  nges pragma].** 
1da30 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65  <li> the [change
1da40 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1da50 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64  ].** <li> the [d
1da60 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67  ata_version prag
1da70 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1da80 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
1da90 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c  TA_VERSION] [fil
1daa0 65 20 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f  e control].** </
1dab0 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul>.*/.int sqlit
1dac0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1dad0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1dae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1daf0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1db00 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
1db10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1db20 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1db30 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
1db40 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
1db50 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
1db60 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1db70 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1db80 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1db90 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1dba0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1dbb0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1dbc0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1dbd0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1dbe0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1dbf0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1dc00 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1dc10 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1dc20 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1dc30 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1dc40 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1dc50 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1dc60 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1dc70 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1dc80 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1dc90 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1dca0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1dcb0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1dcc0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1dcd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1dce0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1dcf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dd00 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1dd10 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1dd20 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1dd30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1dd40 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1dd50 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1dd60 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1dd70 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1dd80 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1dd90 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1dda0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1ddb0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1ddc0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1ddd0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1dde0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1ddf0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1de00 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1de10 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1de20 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1de30 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1de40 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1de50 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1de60 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1de70 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1de80 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1de90 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1dea0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1deb0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1dec0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1ded0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1dee0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1def0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1df00 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1df10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1df20 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1df30 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1df40 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1df50 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1df60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1df70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1df80 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1df90 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1dfa0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1dfb0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1dfc0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1dfd0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1dfe0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1dff0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1e000 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1e010 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1e020 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1e030 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1e040 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1e050 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e060 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1e070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1e080 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1e090 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1e0a0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1e0b0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1e0c0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1e0d0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1e0e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1e0f0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1e100 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e110 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1e120 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1e130 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1e140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1e150 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1e160 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1e170 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1e180 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1e190 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1e1a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1e1b0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a  all returns..*/.
1e1c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
1e1d0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
1e1e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e1f0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1e200 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1e210 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
1e220 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e230 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
1e240 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
1e250 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
1e260 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
1e270 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
1e280 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
1e290 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
1e2a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
1e2b0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
1e2c0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
1e2d0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
1e2e0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
1e2f0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
1e300 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
1e310 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
1e320 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1e330 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
1e340 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
1e350 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
1e360 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
1e370 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
1e380 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
1e390 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
1e3a0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
1e3b0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
1e3c0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
1e3d0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
1e3e0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
1e3f0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
1e400 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
1e410 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
1e420 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
1e430 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
1e440 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
1e450 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
1e460 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
1e470 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
1e480 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
1e490 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
1e4a0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
1e4b0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
1e4c0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
1e4d0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
1e4e0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
1e4f0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
1e500 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
1e510 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
1e520 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1e530 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
1e540 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1e550 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
1e560 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
1e570 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
1e580 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
1e590 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
1e5a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1e5b0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
1e5c0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
1e5d0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
1e5e0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
1e5f0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
1e600 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
1e610 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
1e620 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
1e630 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
1e640 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1e650 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
1e660 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
1e670 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
1e680 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
1e690 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
1e6a0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
1e6b0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
1e6c0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
1e6d0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
1e6e0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
1e6f0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1e700 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1e710 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
1e720 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
1e730 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
1e740 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e750 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
1e760 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
1e770 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1e790 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
1e7a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1e7b0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
1e7c0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1e7d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1e7e0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
1e7f0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1e800 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1e810 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
1e820 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
1e830 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1e840 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1e850 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
1e860 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1e870 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1e880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1e890 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1e8a0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1e8b0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1e8c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
1e8d0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
1e8e0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
1e8f0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
1e900 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1e910 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1e920 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
1e930 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1e940 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1e950 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
1e960 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
1e970 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
1e980 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
1e990 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1e9a0 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1e9b0 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1e9c0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1e9d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1e9e0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1e9f0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1ea00 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1ea10 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1ea20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ea30 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1ea40 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1ea50 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1ea60 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1ea70 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1ea80 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1ea90 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1eaa0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1eab0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1eac0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1ead0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1eae0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1eaf0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1eb00 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1eb10 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1eb20 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1eb30 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1eb40 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1eb50 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1eb60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1eb70 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1eb80 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1eb90 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1eba0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1ebb0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1ebc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1ebd0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1ebe0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1ebf0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1ec00 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1ec10 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1ec20 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1ec30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ec40 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1ec50 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1ec60 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1ec70 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1ec80 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1ec90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1eca0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1ecb0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1ecc0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1ecd0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1ece0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1ecf0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1ed00 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1ed10 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1ed20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ed30 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1ed40 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1ed50 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1ed60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1ed70 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1ed80 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1ed90 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1eda0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1edb0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1edc0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1edd0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1ede0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1edf0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1ee00 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1ee10 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1ee20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1ee30 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1ee40 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1ee50 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1ee60 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1ee70 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1ee80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1ee90 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1eea0 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1eeb0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1eec0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1eed0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1eee0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1eef0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1ef00 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1ef10 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1ef20 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1ef30 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1ef40 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1ef50 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1ef60 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1ef70 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1ef80 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1ef90 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1efa0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1efb0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1efc0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1efd0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1efe0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1eff0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1f000 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1f010 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1f020 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1f030 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1f040 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1f050 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1f060 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1f070 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1f080 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1f090 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1f0a0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1f0b0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1f0c0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1f0d0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1f0e0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1f0f0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1f100 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1f110 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1f120 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1f130 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1f140 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1f150 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1f160 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1f170 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1f180 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1f190 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1f1a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1f1b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1f1c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1f1d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1f1e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1f1f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1f200 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1f210 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1f220 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1f230 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1f240 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1f250 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1f260 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1f270 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1f280 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1f290 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1f2a0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1f2b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1f2c0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1f2d0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1f2e0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1f2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f300 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1f310 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1f320 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1f330 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1f340 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1f350 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1f360 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1f370 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1f380 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1f390 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1f3a0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1f3b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f3c0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1f3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f3e0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1f3f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1f400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f410 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1f420 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1f430 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1f440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f450 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1f460 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1f470 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1f480 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1f490 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1f4a0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1f4b0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1f4c0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1f4d0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1f4e0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1f4f0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1f500 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1f510 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1f520 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1f530 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1f540 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1f550 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1f560 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1f570 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1f580 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1f590 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1f5a0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1f5b0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1f5c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f5d0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1f5e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1f5f0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1f600 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1f610 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1f620 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1f630 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1f640 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1f650 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1f660 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1f670 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1f680 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1f690 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1f6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1f6b0 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1f6c0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1f6d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1f6e0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1f6f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1f700 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1f710 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1f720 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1f730 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1f740 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1f750 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1f760 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1f770 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1f780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1f790 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1f7a0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1f7b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1f7c0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1f7d0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1f7e0 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1f7f0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1f800 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1f810 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1f820 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1f830 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1f840 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1f850 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1f860 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1f870 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1f880 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1f890 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1f8a0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1f8b0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1f8c0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1f8d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1f8e0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1f8f0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1f900 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1f910 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1f920 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1f930 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1f940 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1f950 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1f960 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1f970 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1f980 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1f990 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1f9a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1f9b0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1f9c0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1f9d0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1f9e0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1f9f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1fa00 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1fa10 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1fa20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1fa30 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1fa40 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1fa50 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1fa60 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1fa70 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1fa80 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1fa90 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1faa0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1fab0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1fac0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1fad0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1fae0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1faf0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1fb00 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1fb10 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1fb20 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1fb30 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1fb40 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1fb50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1fb60 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1fb70 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1fb80 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1fb90 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1fba0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1fbb0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1fbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1fbd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1fbe0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1fbf0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1fc00 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1fc10 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1fc20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1fc30 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1fc40 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1fc50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fc60 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1fc70 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1fc80 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1fc90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1fca0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1fcb0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1fcc0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1fcd0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1fce0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1fcf0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1fd00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1fd10 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1fd20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1fd30 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1fd40 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1fd50 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1fd60 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1fd70 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1fd80 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1fd90 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1fda0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1fdb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1fdc0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1fdd0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1fde0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1fdf0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1fe00 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1fe10 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1fe20 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1fe30 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1fe40 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1fe50 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1fe60 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1fe70 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1fe80 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1fe90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1fea0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1feb0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1fec0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1fed0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1fee0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1fef0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1ff00 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1ff10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ff20 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1ff30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ff40 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1ff50 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ff60 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1ff70 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1ff80 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1ff90 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1ffa0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ffb0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1ffc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ffd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1ffe0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1fff0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
20000 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
20010 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
20020 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
20030 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
20040 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
20050 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
20060 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
20070 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
20080 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
20090 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
200a0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
200b0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
200c0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
200d0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
200e0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
200f0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
20100 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
20110 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
20120 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
20130 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
20140 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
20150 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
20160 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
20170 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
20180 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
20190 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
201a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
201b0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
201c0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
201d0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
201e0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
201f0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
20200 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
20210 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
20220 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
20230 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
20240 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
20250 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
20260 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
20270 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
20280 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
20290 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
202a0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
202b0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
202c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
202d0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
202e0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
202f0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
20300 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
20310 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
20320 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
20330 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
20340 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
20350 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
20360 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
20370 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
20380 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
20390 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
203a0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
203b0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
203c0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
203d0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
203e0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
203f0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
20400 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
20410 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
20420 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
20430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
20440 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
20450 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
20460 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
20470 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
20480 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
20490 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
204a0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
204b0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
204c0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
204d0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
204e0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
204f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
20500 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
20510 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
20520 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
20530 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
20540 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
20550 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
20560 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
20570 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
20580 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
20590 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
205a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
205b0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
205c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
205d0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
205e0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
205f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
20600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
20610 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
20620 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
20630 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
20640 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
20650 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
20660 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
20670 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
20680 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
20690 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  on formatting op
206a0 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68  tions from.** th
206b0 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
206c0 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20  ry printf() .** 
206d0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
206e0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
206f0 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c  d formats ([%q],
20700 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64   [%Q], [%w], and
20710 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74   [%z])..** See t
20720 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  he [built-in pri
20730 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  ntf()] documenta
20740 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73  tion for details
20750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20760 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
20770 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
20780 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
20790 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
207a0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
207b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
207c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  [sqlite3_malloc6
207d0 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  4()]..** The str
207e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
207f0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
20800 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
20810 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
20820 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
20830 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
20840 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
20850 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
20860 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20  te3_malloc64()] 
20870 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
20880 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
20890 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
208a0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
208b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
208c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
208d0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
208e0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
208f0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
20900 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
20910 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
20920 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
20930 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
20940 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
20950 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20960 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
20970 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
20980 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
20990 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
209a0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
209b0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
209c0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
209d0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
209e0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
209f0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
20a00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
20a10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
20a20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
20a30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
20a40 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
20a50 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
20a60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
20a70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
20a80 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
20a90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
20aa0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
20ab0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
20ac0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
20ad0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
20ae0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
20af0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
20b00 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
20b10 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
20b20 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
20b30 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
20b40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
20b50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20b60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
20b70 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
20b80 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
20b90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
20ba0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
20bb0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
20bc0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
20bd0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
20be0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
20bf0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
20c00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
20c10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
20c20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
20c30 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
20c40 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
20c50 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
20c60 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
20c70 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
20c80 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
20c90 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
20ca0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
20cb0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
20cc0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
20cd0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
20ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
20cf0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
20d00 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
20d10 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
20d20 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
20d30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75  * See also:  [bu
20d40 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d  ilt-in printf()]
20d50 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20  , [printf() SQL 
20d60 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61  function].*/.cha
20d70 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
20d80 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
20d90 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
20da0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
20db0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
20dc0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
20dd0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
20de0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
20df0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
20e00 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
20e10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
20e20 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
20e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e40 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
20e50 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
20e60 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
20e70 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
20e80 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
20e90 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
20ea0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
20eb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
20ec0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
20ed0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
20ee0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
20ef0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
20f00 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
20f10 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
20f20 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
20f30 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
20f40 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
20f50 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
20f60 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
20f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20f80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
20f90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
20fa0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
20fb0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
20fc0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
20fd0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
20fe0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
20ff0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
21000 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
21010 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
21020 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
21030 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
21040 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
21050 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
21060 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
21070 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21080 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
21090 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
210a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
210b0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
210c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
210d0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
210e0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
210f0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
21100 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21110 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
21120 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
21130 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
21140 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
21150 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
21160 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
21170 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
21180 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
21190 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
211a0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
211b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
211c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
211d0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
211e0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
211f0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
21200 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
21210 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
21220 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
21230 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
21240 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
21250 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
21260 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
21270 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
21280 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
21290 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
212a0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
212b0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
212c0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
212d0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
212e0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
212f0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
21300 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
21310 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
21320 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
21330 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
21340 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
21350 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
21360 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
21370 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
21380 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
21390 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
213a0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
213b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
213c0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
213d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
213e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
213f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
21400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21410 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21420 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
21430 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
21440 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
21450 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
21460 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
21470 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
21480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21490 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
214a0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
214b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
214c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
214d0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
214e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
214f0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
21500 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
21510 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
21520 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
21530 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
21540 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
21550 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
21560 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
21570 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
21580 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
21590 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
215a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
215b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
215c0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
215d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
215e0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
215f0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
21600 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
21610 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
21620 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
21630 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
21640 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
21650 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
21660 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
21670 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
21680 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
21690 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
216a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
216b0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
216c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
216d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
216e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
216f0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
21700 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
21710 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
21720 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
21730 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
21740 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
21750 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
21760 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
21770 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
21780 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
21790 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
217a0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
217b0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
217c0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
217d0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
217e0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
217f0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
21800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21810 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
21820 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
21830 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
21840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
21850 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
21860 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
21870 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
21880 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
21890 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
218a0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
218b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
218c0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
218d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
218e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
218f0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
21900 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
21910 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
21920 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
21930 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
21940 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
21950 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
21960 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
21970 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
21980 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
21990 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
219a0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
219b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
219c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
219d0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
219e0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
219f0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
21a00 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
21a10 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
21a20 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21a30 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
21a40 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
21a50 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
21a60 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
21a70 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
21a80 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
21a90 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
21aa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
21ab0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
21ac0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
21ad0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
21ae0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
21af0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
21b00 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
21b10 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
21b20 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
21b30 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
21b40 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
21b50 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
21b60 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
21b70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
21b80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
21b90 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
21ba0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
21bb0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
21bc0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
21bd0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
21be0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
21bf0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
21c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21c10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
21c20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
21c30 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
21c40 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
21c50 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
21c60 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
21c70 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
21c80 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
21c90 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
21ca0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
21cb0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
21cc0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
21cd0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
21ce0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
21cf0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
21d00 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
21d10 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
21d20 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
21d30 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
21d40 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
21d50 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
21d60 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
21d70 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
21d80 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
21d90 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
21da0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
21db0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
21dc0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
21dd0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
21de0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
21df0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
21e00 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
21e10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21e20 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
21e30 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
21e40 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
21e50 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
21e60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21e70 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
21e80 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
21e90 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
21ea0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
21eb0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
21ec0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
21ed0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
21ee0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
21ef0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
21f00 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
21f10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
21f20 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
21f30 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
21f40 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
21f50 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
21f60 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
21f70 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
21f80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
21f90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
21fa0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
21fb0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
21fc0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
21fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
21fe0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
21ff0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
22000 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
22010 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
22020 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
22030 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
22040 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
22050 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
22060 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
22070 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
22080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22090 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
220a0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
220b0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
220c0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
220d0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
220e0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
220f0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
22100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22110 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
22120 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
22130 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
22140 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
22150 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
22160 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
22170 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
22180 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
22190 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
221a0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
221b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
221c0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
221d0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
221e0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
221f0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
22200 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
22210 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
22220 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
22230 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
22240 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
22250 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
22260 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
22270 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
22280 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
22290 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
222a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
222b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
222c0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
222d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
222e0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
222f0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
22300 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
22310 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
22320 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
22330 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
22340 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
22350 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
22360 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
22370 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
22380 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
22390 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
223a0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
223b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
223c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
223d0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
223e0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
223f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
22400 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
22410 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
22420 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
22430 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
22440 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
22450 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
22460 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
22470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
22480 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
22490 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
224a0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
224b0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
224c0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
224d0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
224e0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
224f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
22500 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
22510 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
22520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
22530 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
22540 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
22550 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
22560 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
22570 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
22580 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
22590 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
225a0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
225b0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
225c0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
225d0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
225e0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
225f0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
22600 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
22610 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
22620 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
22630 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
22640 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
22650 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
22660 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
22670 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
22680 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
22690 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
226a0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
226b0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
226c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
226d0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
226e0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
226f0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
22700 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
22710 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
22720 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
22730 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
22740 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
22750 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
22760 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
22770 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
22780 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
22790 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
227a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
227b0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
227c0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
227d0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
227e0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
227f0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
22800 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
22810 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
22820 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
22830 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
22840 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
22850 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
22860 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
22870 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
22880 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
22890 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
228a0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
228b0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
228c0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
228d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
228e0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
228f0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
22900 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
22910 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
22920 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
22930 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
22940 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
22950 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
22960 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
22980 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22990 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  }.**.** ^This ro
229a0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
229b0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
229c0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
229d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
229e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
229f0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
22a00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22a10 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
22a20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22a30 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
22a40 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
22a50 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
22a60 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
22a70 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
22a80 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
22a90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
22aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22ab0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
22ac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
22ad0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
22ae0 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
22af0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22b00 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e  pare16_v3()].  ^
22b10 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
22b20 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
22b30 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
22b40 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
22b50 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
22b60 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
22b70 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
22b80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22b90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22ba0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
22bb0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
22bc0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
22bd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22be0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
22bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
22c00 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
22c10 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
22c20 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
22c30 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
22c40 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
22c50 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
22c60 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
22c70 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
22c80 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
22c90 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
22ca0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
22cb0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
22cc0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
22cd0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
22ce0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22cf0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
22d00 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
22d10 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
22d20 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
22d30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
22d40 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
22d50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22d60 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
22d70 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
22d80 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
22d90 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
22da0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
22db0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
22dc0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
22dd0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
22de0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
22df0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
22e00 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
22e10 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
22e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
22e30 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
22e40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22e50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22e60 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
22e70 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
22e80 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22e90 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
22ea0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
22eb0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
22ec0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
22ed0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
22ee0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22ef0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
22f00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22f10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
22f20 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
22f30 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
22f40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
22f50 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
22f60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22f70 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
22f80 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
22f90 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
22fa0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
22fb0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
22fc0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
22fd0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
22fe0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
22ff0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
23000 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
23010 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
23020 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c   are either NULL
23030 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72   pointers or zer
23040 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
23050 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e  ings.** that con
23060 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  tain additional 
23070 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
23080 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
23090 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70  uthorized..** Ap
230a0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
230b0 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72  always be prepar
230c0 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20  ed to encounter 
230d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
230e0 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  n any.** of the 
230f0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68  third through th
23100 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
23110 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72  rs of the author
23120 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
23130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23140 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
23150 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
23160 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
23170 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
23180 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
23190 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
231a0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
231b0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
231c0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
231d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
231e0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
231f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
23200 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
23210 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
23220 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
23230 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
23240 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
23250 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
23260 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
23270 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
23280 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
23290 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
232a0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
232b0 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69   ^When a table i
232c0 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20  s referenced by 
232d0 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e  a [SELECT] but n
232e0 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  o column values 
232f0 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64  are.** extracted
23300 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65   from that table
23310 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e   (for example in
23320 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a   a query like.**
23330 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a   "SELECT count(*
23340 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65  ) FROM tab") the
23350 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45  n the [SQLITE_RE
23360 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63  AD] authorizer c
23370 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e  allback.** is in
23380 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74  voked once for t
23390 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61  hat table with a
233a0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61   column name tha
233b0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  t is an empty st
233c0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
233d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
233e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
233f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
23400 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
23410 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
23420 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
23430 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
23440 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
23450 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
23460 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
23470 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
23480 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
23490 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
234a0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
234b0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
234c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
234d0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
234e0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
234f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
23500 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
23510 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
23520 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
23530 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
23540 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
23550 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
23560 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
23570 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
23580 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
23590 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
235a0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
235b0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
235c0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
235d0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
235e0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
235f0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
23600 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
23610 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
23620 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
23630 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
23640 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
23650 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
23660 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
23670 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
23680 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
23690 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
236a0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
236b0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
236c0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
236d0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
236e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
236f0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
23700 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
23710 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
23720 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
23730 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
23740 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
23750 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
23760 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
23770 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
23780 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
23790 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
237a0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
237b0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
237c0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
237d0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
237e0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
237f0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
23800 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
23810 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
23820 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
23830 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
23840 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
23850 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
23860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23870 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
23880 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
23890 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
238a0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
238b0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
238c0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
238d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
238e0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
238f0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
23900 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
23910 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
23920 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
23930 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23940 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
23950 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
23960 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
23970 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23980 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
23990 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
239a0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
239b0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
239c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
239d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
239e0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
239f0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23a00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23a10 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23a20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23a30 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
23a40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
23a50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23a60 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
23a70 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
23a80 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
23a90 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
23aa0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
23ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23ac0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
23ad0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
23ae0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
23af0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
23b00 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
23b10 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
23b20 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
23b30 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
23b40 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
23b50 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
23b60 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
23b70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23b80 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
23b90 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
23ba0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
23bb0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
23bc0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
23bd0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
23be0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
23bf0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
23c00 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
23c10 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
23c20 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
23c30 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
23c40 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
23c50 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
23c60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23c70 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
23c80 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
23c90 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
23ca0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23cb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
23cc0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
23cd0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
23ce0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
23cf0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
23d00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
23d10 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
23d20 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
23d30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
23d40 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
23d50 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
23d60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
23d70 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
23d80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
23d90 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
23da0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
23db0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
23dc0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
23dd0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
23de0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
23df0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
23e00 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
23e10 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
23e20 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
23e30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
23e40 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
23e50 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
23e60 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23e70 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23e80 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
23e90 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
23ea0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
23eb0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
23ec0 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
23ed0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
23ee0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
23ef0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
23f00 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
23f10 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
23f20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
23f30 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
23f40 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
23f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
23f60 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
23f70 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
23f80 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
23f90 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
23fa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
23fb0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
23fc0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
23fd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
23fe0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
23ff0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
24000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24010 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
24020 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
24030 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
24040 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
24050 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
24060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24070 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
24080 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
24090 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
240a0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
240b0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
240c0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
240d0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
240e0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
240f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
24100 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
24110 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
24120 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
24130 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
24140 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
24150 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
24160 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
24170 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
24180 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
24190 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
241a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
241b0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
241c0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
241d0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
241e0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
241f0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
24200 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
24210 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
24220 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
24230 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
24240 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
24250 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
24260 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
24270 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
24280 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
24290 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
242a0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
242b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
242c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
242d0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
242e0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
242f0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
24300 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
24310 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
24320 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
24330 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
24340 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
24350 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
24360 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
24370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24380 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
24390 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
243a0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
243b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
243c0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
243d0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
243e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
243f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24410 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
24420 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
24430 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24440 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24460 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
24470 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
24480 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
24490 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
244a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
244b0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
244c0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
244d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
244e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
244f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24500 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
24510 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
24520 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
24530 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24540 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24550 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
24560 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
24570 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
24580 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24590 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
245a0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
245b0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
245c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
245d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
245e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
245f0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
24600 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
24610 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24620 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24630 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
24640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
24650 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24660 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24680 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
24690 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
246a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
246b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
246c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
246d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
246e0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
246f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24700 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24720 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
24730 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
24740 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24750 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24770 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
24780 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
24790 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
247a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
247b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
247c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
247d0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
247e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
247f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24810 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
24820 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
24830 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
24840 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24860 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
24870 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
24880 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24890 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
248a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
248b0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
248c0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
248d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
248e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
248f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24900 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
24910 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
24920 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
24950 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
24960 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
24970 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
24980 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
24990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
249a0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
249b0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
249c0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
249d0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
249e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
249f0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
24a00 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
24a10 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
24a20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
24a40 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
24a50 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
24a60 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
24a70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24a80 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
24a90 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
24aa0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
24ab0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
24ac0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
24ad0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
24ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
24af0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
24b00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24b10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24b20 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
24b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
24b40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
24b50 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
24b60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24b70 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
24b80 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
24b90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
24ba0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
24bb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24bc0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
24bd0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
24be0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
24bf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24c00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24c10 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
24c20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
24c30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24c40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24c50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24c60 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
24c70 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
24c80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24c90 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
24ca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24cb0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
24cc0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
24cd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24ce0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
24cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24d00 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
24d10 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
24d20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24d30 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
24d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24d50 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
24d60 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
24d70 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
24d80 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
24d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24da0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
24db0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
24dc0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
24dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
24de0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
24df0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
24e00 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
24e10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
24e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e30 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
24e40 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
24e50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
24e60 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
24e70 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72  outines are depr
24e80 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20  ecated. Use the 
24e90 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24ea0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  2()] interface.*
24eb0 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  * instead of the
24ec0 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69   routines descri
24ed0 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  bed here..**.** 
24ee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
24ef0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
24f00 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
24f10 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
24f20 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
24f30 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
24f40 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
24f50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
24f60 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
24f70 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
24f80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
24f90 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
24fa0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
24fb0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
24fc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
24fd0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
24fe0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
24ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
25000 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
25010 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
25020 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
25030 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
25040 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
25050 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
25060 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
25070 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
25080 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
25090 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
250a0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
250b0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
250c0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
250d0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
250e0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
250f0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
25100 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
25110 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
25120 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
25130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
25140 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
25150 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
25160 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
25170 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
25180 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
25190 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
251a0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
251b0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
251c0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
251d0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
251e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
251f0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
25200 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
25210 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
25220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
25230 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
25240 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
25250 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
25260 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
25270 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
25280 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
25290 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
252a0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
252b0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
252c0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
252d0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
252e0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
252f0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
25300 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
25310 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
25320 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
25330 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
25340 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
25350 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
25360 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
25370 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
25380 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
25390 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
253a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
253b0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
253c0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
253d0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
253e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e  er callback.  In
253f0 76 6f 6b 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72  voking.** either
25400 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
25410 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  )] or [sqlite3_t
25420 72 61 63 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20  race_v2()] will 
25430 63 61 6e 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72  cancel the.** pr
25440 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  ofile callback..
25450 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
25460 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
25470 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
25480 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
25490 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
254a0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
254b0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
254c0 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
254d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
254e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
254f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
25500 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
25510 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
25520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25530 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
25540 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
25550 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
25560 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
25570 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
25580 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
25590 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
255a0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
255b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
255c0 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
255d0 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20  g logic.  The M 
255e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
255f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25600 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e  (D,M,X,P)] is an
25610 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
25620 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
25630 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
25640 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
25650 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
25660 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
25670 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
25680 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
25690 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
256a0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
256b0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
256c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
256d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
256e0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
256f0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
25700 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
25710 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
25720 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
25730 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
25740 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
25750 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
25760 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
25770 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
25780 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
25790 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
257a0 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
257b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
257c0 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
257d0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
257e0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
257f0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
25800 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
25810 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
25820 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
25830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
25840 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
25850 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
25860 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
25870 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
25880 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
25890 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
258a0 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
258b0 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
258c0 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
258d0 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
258e0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
258f0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
25900 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
25910 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
25920 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
25930 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
25940 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
25950 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
25960 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
25970 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
25980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
25990 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
259a0 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
259b0 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
259c0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
259d0 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
259e0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
259f0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
25a00 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
25a10 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
25a20 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
25a30 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
25a40 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
25a50 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
25a60 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
25a70 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
25a80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
25a90 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
25aa0 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
25ab0 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
25ac0 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
25ad0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
25ae0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
25af0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
25b00 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
25b10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
25b20 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
25b30 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
25b40 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
25b50 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
25b60 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
25b70 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
25b80 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
25b90 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
25ba0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
25bb0 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
25bc0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25bd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25be0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25bf0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
25c00 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
25c10 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
25c20 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
25c30 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
25c40 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
25c50 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
25c60 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
25c70 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
25c80 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
25c90 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
25ca0 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
25cb0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
25cc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
25cd0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
25ce0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
25cf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
25d00 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
25d10 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
25d20 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
25d30 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25d40 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
25d50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
25d60 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
25d70 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
25d80 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
25d90 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
25da0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
25db0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
25dc0 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
25dd0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
25de0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
25df0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
25e00 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
25e10 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
25e20 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
25e30 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
25e40 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
25e50 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
25e60 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
25e70 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
25e80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
25e90 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
25ea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
25eb0 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
25ec0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
25ed0 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
25ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
25ef0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
25f00 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
25f10 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
25f20 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
25f30 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
25f40 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
25f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
25f60 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
25f70 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
25f80 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
25f90 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
25fa0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
25fb0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
25fc0 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
25fd0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
25fe0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
25ff0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
26000 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
26010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
26020 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
26030 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
26040 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
26050 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
26060 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
26070 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
26080 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
26090 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
260a0 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
260b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
260c0 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
260d0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
260e0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
260f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
26100 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
26110 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
26120 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
26130 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
26140 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
26150 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
26160 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
26170 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
26180 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
26190 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
261a0 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
261b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
261c0 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
261d0 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
261e0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
261f0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
26200 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
26210 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
26220 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
26230 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
26240 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
26250 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
26260 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
26270 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
26280 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
26290 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
262a0 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
262b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
262c0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
262d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
262e0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
262f0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
26300 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
26310 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
26320 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
26330 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
26340 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
26350 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
26360 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
26370 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
26380 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
26390 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
263a0 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
263b0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
263c0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
263d0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
263e0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
263f0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
26400 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
26410 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
26420 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
26430 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
26440 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
26450 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
26460 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
26470 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
26480 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
26490 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
264a0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
264b0 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
264c0 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
264d0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
264e0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
264f0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
26500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
26510 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
26520 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
26530 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
26540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
26550 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
26560 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
26570 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
26580 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
26590 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
265a0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
265b0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
265c0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
265d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
265e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
265f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
26600 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
26610 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
26620 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
26630 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
26640 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
26650 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
26660 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
26670 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
26680 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
26690 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
266a0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
266b0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
266c0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
266d0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
266e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
266f0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
26700 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
26710 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
26720 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
26730 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
26740 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
26750 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
26760 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
26770 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
26780 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
26790 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
267a0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
267b0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
267c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
267d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
267e0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
267f0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
26800 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26810 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
26820 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
26830 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
26840 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
26850 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
26860 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
26870 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
26880 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
26890 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
268a0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
268b0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
268c0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
268d0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
268e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
268f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
26900 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
26910 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
26920 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
26930 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
26940 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
26950 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
26960 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
26970 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
26980 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
26990 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
269a0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
269b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
269c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
269d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
269e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
269f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
26a00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
26a10 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
26a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26a30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
26a40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
26a50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
26a60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26a70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
26a80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
26a90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
26aa0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
26ab0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
26ac0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
26ad0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
26ae0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
26af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26b00 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
26b10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
26b20 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
26b30 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
26b40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
26b50 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
26b60 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
26b70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
26b80 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
26b90 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
26ba0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
26bb0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
26bc0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
26bd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
26be0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26bf0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
26c00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
26c10 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
26c20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
26c30 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
26c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
26c50 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
26c60 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
26c70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
26c80 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
26c90 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
26ca0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
26cb0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
26cc0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
26cd0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
26ce0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
26cf0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
26d00 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
26d10 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
26d20 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
26d30 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
26d40 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
26d50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26d60 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
26d70 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
26d80 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
26d90 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
26da0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
26db0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
26dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
26dd0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
26de0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
26df0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
26e00 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
26e10 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
26e20 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
26e30 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
26e40 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
26e50 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
26e60 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
26e70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
26e80 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
26e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
26ea0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
26eb0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
26ec0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
26ed0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
26ee0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
26ef0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
26f00 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
26f10 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
26f20 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
26f30 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
26f40 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
26f50 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
26f60 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
26f70 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
26f80 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
26f90 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
26fa0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
26fb0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
26fc0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
26fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
26fe0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
26ff0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
27000 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
27010 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
27020 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
27030 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
27040 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
27050 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
27060 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
27070 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
27080 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
27090 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
270a0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
270b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
270c0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
270d0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
270e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
270f0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
27100 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
27110 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
27120 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
27130 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
27140 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
27150 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
27160 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
27170 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
27180 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
27190 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
271a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
271b0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
271c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
271d0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
271e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
271f0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
27200 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
27210 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
27220 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
27230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27240 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
27250 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
27260 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
27270 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
27280 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
27290 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
272a0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
272b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
272c0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
272d0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
272e0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
272f0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
27300 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
27310 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
27320 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
27330 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
27340 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
27350 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
27360 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
27370 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
27380 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
27390 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
273a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
273b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
273c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
273d0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
273e0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
273f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
27400 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27410 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
27420 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
27430 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
27440 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
27450 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
27460 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
27470 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
27480 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
27490 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
274a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
274b0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
274c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
274d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
274e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
274f0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
27500 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
27510 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
27520 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
27530 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
27540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
27550 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
27560 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
27570 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27580 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
275a0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
275b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
275c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
275d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
275e0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
275f0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
27600 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
27610 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
27620 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
27630 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
27640 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
27650 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
27660 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
27670 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
27680 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
27690 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
276a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
276b0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
276c0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
276d0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
276e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
276f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
27700 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
27710 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
27720 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
27730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
27740 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
27750 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
27760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
27770 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
27780 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
27790 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
277a0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
277b0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
277c0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
277d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
277e0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
277f0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
27800 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
27810 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
27820 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
27830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27840 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
27850 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
27860 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
27870 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
27880 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
27890 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
278a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
278b0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
278c0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
278d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
278e0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
278f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
27900 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
27910 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
27920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27930 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
27940 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
27950 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
27960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
27970 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
27980 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
27990 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
279a0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
279b0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
279c0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
279d0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
279e0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
279f0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
27a00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
27a10 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
27a20 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
27a30 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
27a40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27a50 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
27a60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
27a70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
27a80 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
27a90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
27aa0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
27ab0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
27ac0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
27ad0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
27ae0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
27af0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27b00 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
27b10 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
27b20 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
27b30 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
27b40 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
27b50 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
27b60 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
27b70 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
27b80 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
27b90 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
27ba0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
27bb0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
27bc0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
27bd0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
27be0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
27bf0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
27c00 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
27c10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
27c20 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
27c30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
27c40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
27c50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
27c60 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
27c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
27c80 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
27c90 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
27ca0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
27cb0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
27cc0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
27cd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
27ce0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
27cf0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
27d00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
27d10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
27d20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
27d30 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
27d40 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
27d50 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
27d60 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
27d70 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
27d80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
27d90 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27da0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
27db0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
27dc0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
27dd0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
27de0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
27df0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
27e00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
27e10 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
27e20 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
27e30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
27e40 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69  ption..** URI fi
27e50 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
27e60 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
27e70 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
27e80 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
27e90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
27ea0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
27eb0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
27ec0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
27ed0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
27ee0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
27ef0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
27f00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
27f10 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
27f20 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
27f30 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
27f40 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
27f50 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
27f60 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
27f70 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
27f80 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
27f90 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
27fa0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
27fb0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
27fc0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
27fd0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
27fe0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
27ff0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
28000 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
28010 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
28020 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
28030 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
28040 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
28050 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
28060 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
28070 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
28080 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
28090 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
280a0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
280b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
280c0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
280d0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
280e0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
280f0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
28100 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
28110 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
28120 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
28130 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
28140 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
28150 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
28160 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
28170 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
28180 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
28190 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
281a0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
281b0 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
281c0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
281d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
281e0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
281f0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
28200 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
28210 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
28220 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
28230 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
28240 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
28250 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
28260 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
28270 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
28280 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
28290 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
282a0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
282b0 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
282c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
282d0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
282e0 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
282f0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
28300 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
28310 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
28320 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
28330 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
28340 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
28350 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
28360 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
28370 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
28380 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
28390 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
283a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
283b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
283c0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
283d0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
283e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
283f0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
28400 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
28410 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
28420 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
28430 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
28440 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
28450 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
28460 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
28470 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
28480 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28490 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
284a0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
284b0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
284c0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
284d0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
284e0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
284f0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
28500 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
28510 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
28520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28530 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
28540 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
28550 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
28560 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
28570 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
28580 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
28590 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
285a0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
285b0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
285c0 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
285d0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
285e0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
285f0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
28600 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
28610 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
28620 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
28630 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
28640 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
28650 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
28660 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
28670 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
28680 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
28690 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
286a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
286b0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
286c0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
286d0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
286e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
286f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
28700 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
28710 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
28720 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
28730 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
28740 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
28750 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
28760 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
28770 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
28780 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
28790 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
287a0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
287b0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
287c0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
287d0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
287e0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
287f0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
28800 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
28810 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
28820 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
28830 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
28840 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
28850 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
28860 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
28870 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
28880 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
28890 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
288a0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
288b0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
288c0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
288d0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
288e0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
288f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28900 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
28910 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
28920 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
28930 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
28940 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
28950 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
28960 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
28970 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
28980 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
28990 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
289a0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
289b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
289c0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
289d0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
289e0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
289f0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
28a00 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
28a10 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
28a20 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
28a30 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
28a40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
28a50 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
28a60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
28a70 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
28a80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
28a90 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
28aa0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
28ab0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
28ac0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
28ad0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
28ae0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
28af0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
28b00 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
28b10 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
28b20 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
28b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
28b40 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
28b50 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
28b60 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
28b70 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
28b80 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
28b90 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
28ba0 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
28bb0 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
28bc0 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
28bd0 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
28be0 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
28bf0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
28c00 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
28c10 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
28c20 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
28c30 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
28c40 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
28c50 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
28c60 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
28c70 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
28c80 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
28c90 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
28ca0 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
28cb0 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
28cc0 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
28cd0 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
28ce0 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
28cf0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
28d00 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
28d10 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
28d20 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
28d30 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
28d40 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
28d50 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
28d60 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
28d70 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
28d80 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
28d90 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
28da0 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
28db0 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
28dc0 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
28dd0 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
28de0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
28df0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
28e00 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
28e10 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
28e20 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
28e30 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
28e40 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
28e50 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
28e60 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
28e70 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28e80 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
28e90 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
28ea0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
28eb0 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
28ec0 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
28ed0 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
28ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
28ef0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
28f00 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
28f10 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
28f20 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
28f30 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
28f40 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
28f50 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
28f60 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
28f70 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
28f80 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
28f90 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
28fa0 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
28fb0 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
28fc0 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
28fd0 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
28fe0 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
28ff0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
29000 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
29010 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
29020 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
29030 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
29040 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
29050 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
29060 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
29070 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
29080 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
29090 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
290a0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
290b0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
290c0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
290d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
290e0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
290f0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
29100 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
29110 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
29120 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
29130 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
29140 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
29150 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
29160 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
29170 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
29180 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
29190 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
291a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
291b0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
291c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
291d0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
291e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
291f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
29200 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
29210 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
29220 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
29230 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
29240 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
29250 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
29260 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
29270 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
29280 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
29290 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
292a0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
292b0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
292c0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
292d0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
292e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
292f0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
29300 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
29310 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
29320 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
29330 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
29340 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
29350 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
29360 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
29370 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
29380 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
29390 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
293a0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
293b0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
293c0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
293d0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
293e0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
293f0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
29400 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
29410 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
29420 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
29430 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
29440 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
29450 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
29460 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
29470 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
29480 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
29490 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
294a0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
294b0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
294c0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
294d0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
294e0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
294f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
29500 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
29510 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
29520 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
29530 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
29540 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
29550 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
29560 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
29570 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
29580 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
29590 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
295a0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
295b0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
295c0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
295d0 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
295e0 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
295f0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
29600 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29610 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
29620 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
29630 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
29640 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
29650 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
29660 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
29670 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
29680 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
29690 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
296a0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
296b0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
296c0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
296d0 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
296e0 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
296f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
29700 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
29710 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
29720 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
29730 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
29740 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
29750 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
29760 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
29770 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
29780 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
29790 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
297a0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
297b0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
297c0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
297d0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
297e0 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
297f0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
29800 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
29810 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
29820 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
29830 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
29840 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
29850 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
29860 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
29870 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
29880 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
29890 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
298a0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
298b0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
298c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
298d0 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
298e0 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
298f0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
29900 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
29910 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
29920 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
29930 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
29940 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
29950 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
29960 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
29970 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
29980 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
29990 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
299a0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
299b0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
299c0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
299d0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
299e0 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
299f0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
29a00 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
29a10 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
29a20 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
29a30 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
29a40 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
29a50 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
29a60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
29a70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
29a80 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
29a90 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
29aa0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
29ab0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
29ac0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
29ad0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
29ae0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
29af0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
29b00 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
29b10 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
29b20 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
29b30 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
29b40 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
29b50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29b60 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
29b70 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
29b80 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
29b90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
29ba0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
29bb0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
29bc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
29bd0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
29be0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
29bf0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
29c00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
29c10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
29c20 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
29c30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
29c40 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
29c50 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
29c60 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
29c70 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
29c80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
29c90 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
29ca0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
29cb0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
29cc0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
29cd0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
29ce0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
29cf0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
29d00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
29d10 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
29d20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
29d30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
29d40 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
29d50 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
29d60 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
29d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
29d80 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
29d90 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
29da0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
29db0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
29dc0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
29dd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
29de0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
29df0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
29e00 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
29e10 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
29e20 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
29e30 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
29e40 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
29e50 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
29e60 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
29e70 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
29e80 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
29e90 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
29ea0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
29eb0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
29ec0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
29ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
29ee0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
29ef0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
29f00 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
29f10 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
29f20 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
29f30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
29f40 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
29f50 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
29f60 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
29f70 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
29f80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
29f90 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
29fa0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
29fb0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
29fc0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
29fd0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
29fe0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
29ff0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
2a000 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
2a010 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
2a020 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
2a030 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
2a040 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
2a050 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
2a060 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
2a070 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
2a080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2a090 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
2a0a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a0b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a0c0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
2a0d0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
2a0e0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
2a0f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
2a100 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
2a110 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
2a120 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
2a130 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
2a140 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
2a150 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
2a160 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
2a170 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
2a180 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
2a190 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
2a1a0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
2a1b0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
2a1c0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
2a1d0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
2a1e0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
2a1f0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
2a200 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2a210 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
2a220 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
2a230 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
2a240 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
2a250 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
2a260 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
2a270 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
2a280 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
2a290 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
2a2a0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
2a2b0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
2a2c0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
2a2d0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
2a2e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
2a2f0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
2a300 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
2a310 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
2a320 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2a330 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
2a340 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
2a350 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
2a360 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
2a370 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
2a380 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
2a390 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
2a3a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
2a3b0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
2a3c0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
2a3d0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
2a3e0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
2a3f0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
2a400 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
2a410 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
2a420 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
2a430 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
2a440 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
2a450 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
2a460 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
2a470 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
2a480 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
2a490 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
2a4a0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
2a4b0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
2a4c0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
2a4d0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
2a4e0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
2a4f0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
2a500 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
2a510 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
2a520 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
2a530 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
2a540 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
2a550 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2a560 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
2a570 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  e..**.** See the
2a580 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
2a590 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2a5a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2a5b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e  ormation..*/.con
2a5c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a5d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
2a5e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2a5f0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
2a600 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
2a610 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
2a620 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
2a630 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
2a640 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
2a650 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
2a660 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
2a670 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
2a680 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
2a690 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2a6a0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2a6b0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
2a6c0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
2a6d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2a6e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2a6f0 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
2a700 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
2a710 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
2a720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2a730 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
2a740 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
2a750 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
2a760 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
2a770 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
2a780 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
2a790 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2a7a0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
2a7b0 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
2a7c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
2a7d0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
2a7e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
2a7f0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
2a800 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
2a810 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
2a820 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2a830 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
2a840 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2a850 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
2a860 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  abled..**.** The
2a870 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2a880 20 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63   by sqlite3_errc
2a890 6f 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20  ode() and/or.** 
2a8a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2a8b0 5f 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74  _errcode() might
2a8c0 20 63 68 61 6e 67 65 20 77 69 74 68 20 65 61 63   change with eac
2a8d0 68 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45  h API call..** E
2a8e0 78 63 65 70 74 2c 20 74 68 65 72 65 20 61 72 65  xcept, there are
2a8f0 20 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   some interfaces
2a900 20 74 68 61 74 20 61 72 65 20 67 75 61 72 61 6e   that are guaran
2a910 74 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a  teed to never.**
2a920 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2a930 65 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63  e of the error c
2a940 6f 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d  ode.  The error-
2a950 63 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a  code preserving.
2a960 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
2a970 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
2a980 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72   <li> sqlite3_er
2a990 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20  rcode().** <li> 
2a9a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2a9b0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c  _errcode().** <l
2a9c0 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  i> sqlite3_errms
2a9d0 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  g().** <li> sqli
2a9e0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a  te3_errmsg16().*
2a9f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54  * </ul>.**.** ^T
2aa00 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
2aa10 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
2aa20 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
2aa30 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
2aa40 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
2aa50 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2aa60 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
2aa70 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
2aa80 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2aa90 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
2aaa0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2aab0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
2aac0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
2aad0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2aae0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
2aaf0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
2ab00 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
2ab10 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
2ab20 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
2ab30 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
2ab40 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
2ab50 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
2ab60 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2ab70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
2ab80 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
2ab90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2aba0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
2abb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2abc0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
2abd0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
2abe0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
2abf0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
2ac00 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
2ac10 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
2ac20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2ac30 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
2ac40 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
2ac50 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
2ac60 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
2ac70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
2ac80 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
2ac90 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
2aca0 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
2acb0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
2acc0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
2acd0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
2ace0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
2acf0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
2ad00 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
2ad10 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
2ad20 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
2ad30 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
2ad40 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
2ad50 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
2ad60 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
2ad70 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
2ad80 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
2ad90 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
2ada0 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
2adb0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
2adc0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
2add0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
2ade0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
2adf0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
2ae00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ae10 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
2ae20 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
2ae30 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
2ae40 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
2ae50 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
2ae60 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
2ae70 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
2ae80 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
2ae90 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2aea0 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
2aeb0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
2aec0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
2aed0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
2aee0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
2aef0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
2af00 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
2af10 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
2af20 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
2af30 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
2af40 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
2af50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
2af60 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
2af70 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
2af80 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
2af90 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
2afa0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
2afb0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
2afc0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
2afd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
2afe0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
2aff0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
2b000 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
2b010 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
2b020 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
2b030 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
2b040 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2b050 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
2b060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b070 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
2b080 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2b090 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
2b0a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
2b0b0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
2b0c0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
2b0d0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2b0e0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
2b0f0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
2b100 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
2b110 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
2b120 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
2b130 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
2b140 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
2b150 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
2b160 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
2b170 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
2b180 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
2b190 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
2b1a0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
2b1b0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
2b1c0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
2b1d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
2b1e0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
2b1f0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
2b200 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
2b210 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
2b220 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2b230 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
2b240 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
2b250 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
2b260 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
2b270 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2b280 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
2b290 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
2b2a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
2b2b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b2c0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2b2d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2b2e0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
2b2f0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
2b300 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
2b310 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2b320 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
2b330 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
2b340 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
2b350 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
2b360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b370 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2b380 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
2b390 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b3a0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2b3b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b3c0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
2b3d0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
2b3e0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
2b3f0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
2b400 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
2b410 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
2b420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b430 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
2b440 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2b450 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
2b460 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
2b470 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
2b480 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
2b490 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2b4a0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
2b4b0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
2b4c0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
2b4d0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
2b4e0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
2b4f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
2b500 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
2b510 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
2b520 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2b530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b540 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
2b550 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
2b560 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
2b570 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
2b580 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
2b590 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
2b5a0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
2b5b0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
2b5c0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
2b5d0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
2b5e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b5f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
2b600 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
2b610 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
2b620 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
2b630 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
2b640 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
2b650 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
2b660 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
2b670 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
2b680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
2b690 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
2b6a0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
2b6b0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
2b6c0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
2b6d0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
2b6e0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
2b6f0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
2b700 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
2b710 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
2b720 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
2b730 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
2b740 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
2b750 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
2b760 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
2b770 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
2b780 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
2b790 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
2b7a0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
2b7b0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
2b7c0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
2b7d0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
2b7e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2b7f0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
2b800 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
2b810 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
2b820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b830 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
2b840 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
2b850 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
2b860 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
2b870 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
2b880 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
2b890 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
2b8a0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
2b8b0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
2b8c0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
2b8d0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
2b8e0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
2b8f0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2b900 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
2b910 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
2b920 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
2b930 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2b940 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
2b950 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
2b960 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
2b970 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
2b980 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
2b990 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
2b9a0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
2b9b0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
2b9c0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
2b9d0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
2b9e0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
2b9f0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
2ba00 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
2ba10 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
2ba20 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
2ba30 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
2ba40 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
2ba50 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2ba60 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
2ba70 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
2ba80 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
2ba90 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
2baa0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
2bab0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
2bac0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
2bad0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
2bae0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
2baf0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
2bb00 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
2bb10 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
2bb20 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
2bb30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
2bb40 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
2bb50 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
2bb60 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
2bb70 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
2bb80 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
2bb90 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
2bba0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
2bbb0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
2bbc0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
2bbd0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
2bbe0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
2bbf0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
2bc00 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
2bc10 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
2bc20 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2bc30 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
2bc40 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
2bc50 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
2bc60 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
2bc70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
2bc80 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
2bc90 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
2bca0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
2bcb0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
2bcc0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
2bcd0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2bce0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
2bcf0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
2bd00 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2bd10 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
2bd20 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
2bd30 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
2bd40 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
2bd50 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
2bd60 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
2bd70 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
2bd80 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
2bd90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2bda0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
2bdb0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
2bdc0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
2bdd0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2bde0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
2bdf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2be00 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
2be10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2be20 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
2be30 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
2be40 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
2be50 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
2be60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2be70 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
2be80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2be90 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
2bea0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2beb0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
2bec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2bed0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
2bee0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2bef0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
2bf00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bf10 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
2bf20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2bf30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2bf40 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
2bf50 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
2bf60 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
2bf70 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
2bf80 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
2bf90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2bfa0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
2bfb0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
2bfc0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
2bfd0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
2bfe0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2bff0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
2c000 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c010 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
2c020 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c030 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
2c040 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
2c050 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
2c060 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2c070 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2c080 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
2c090 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2c0a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
2c0b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c0c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c0d0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
2c0e0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
2c0f0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
2c100 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2c110 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
2c120 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c130 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
2c140 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2c150 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
2c160 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
2c170 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
2c180 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
2c190 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
2c1a0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
2c1b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c1c0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
2c1d0 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
2c1e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
2c1f0 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
2c200 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
2c210 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
2c220 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2c230 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
2c240 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
2c250 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
2c260 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2c270 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2c280 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
2c290 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2c2a0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
2c2b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2c2c0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2c2d0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
2c2e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2c2f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2c300 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
2c310 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2c320 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
2c330 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2c340 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
2c350 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2c360 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
2c370 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2c380 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2c390 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
2c3a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2c3b0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
2c3c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c3d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c3e0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
2c3f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
2c400 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
2c410 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
2c420 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2c430 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2c440 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
2c450 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c460 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
2c470 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c480 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
2c490 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
2c4a0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
2c4b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
2c4c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c4d0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2c4e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c4f0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2c500 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2c510 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2c520 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
2c530 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
2c540 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2c550 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2c560 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
2c570 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
2c580 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
2c590 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c5a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2c5b0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
2c5c0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
2c5d0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
2c5e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
2c5f0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
2c600 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2c610 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c620 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2c630 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
2c640 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c650 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
2c660 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
2c670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c680 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
2c690 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2c6a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c6b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2c6d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c6e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2c6f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2c700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c710 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2c720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c730 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2c740 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2c750 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2c760 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2c770 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2c780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c790 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2c7a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2c7b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2c7c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2c7d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2c7e0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2c7f0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2c800 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2c810 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2c820 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2c830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2c840 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2c850 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2c860 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2c870 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2c880 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2c890 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2c8a0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2c8b0 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2c8c0 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2c8d0 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2c8e0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2c8f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2c900 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2c910 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2c920 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2c930 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2c940 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2c950 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2c960 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2c970 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c980 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2c990 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2c9a0 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2c9b0 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2c9c0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2c9d0 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2c9e0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2c9f0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2ca00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ca10 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2ca20 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2ca30 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2ca40 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2ca50 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2ca60 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2ca70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2ca80 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2ca90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2caa0 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2cab0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2cac0 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2cad0 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2cae0 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2caf0 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2cb00 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2cb10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2cb20 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2cb30 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2cb40 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2cb50 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2cb60 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2cb70 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2cb80 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2cb90 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2cba0 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2cbb0 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2cbc0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2cbd0 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2cbe0 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2cbf0 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2cc00 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2cc10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2cc20 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a  PREPARE_NORMALIZ
2cc30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50  E]] <dt>SQLITE_P
2cc40 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2cc50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2cc60 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2cc70 4e 4f 52 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69  NORMALIZE flag i
2cc80 73 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20  s a no-op. This 
2cc90 66 6c 61 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20  flag used.** to 
2cca0 62 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  be required for 
2ccb0 61 6e 79 20 70 72 65 70 61 72 65 64 20 73 74 61  any prepared sta
2ccc0 74 65 6d 65 6e 74 20 74 68 61 74 20 77 61 6e 74  tement that want
2ccd0 65 64 20 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a  ed to use the.**
2cce0 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c   [sqlite3_normal
2ccf0 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65  ized_sql()] inte
2cd00 72 66 61 63 65 2e 20 20 48 6f 77 65 76 65 72 2c  rface.  However,
2cd10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2cd20 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2cd30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
2cd40 6e 6f 77 20 61 76 61 69 6c 61 62 6c 65 20 74 6f  now available to
2cd50 20 61 6c 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64   all.** prepared
2cd60 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 72 65 67   statements, reg
2cd70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2cd80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 79 20 75  er or not they u
2cd90 73 65 20 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e  se this.** flag.
2cda0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2cdb0 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d  PREPARE_NO_VTAB]
2cdc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45  ] <dt>SQLITE_PRE
2cdd0 50 41 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74  PARE_NO_VTAB</dt
2cde0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
2cdf0 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56  ITE_PREPARE_NO_V
2ce00 54 41 42 20 66 6c 61 67 20 63 61 75 73 65 73 20  TAB flag causes 
2ce10 74 68 65 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72  the SQL compiler
2ce20 0a 2a 2a 20 74 6f 20 72 65 74 75 72 6e 20 61 6e  .** to return an
2ce30 20 65 72 72 6f 72 20 28 65 72 72 6f 72 20 63 6f   error (error co
2ce40 64 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 29  de SQLITE_ERROR)
2ce50 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2ce60 74 20 75 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69  t uses.** any vi
2ce70 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
2ce80 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2ce90 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2cea0 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20 20 20  _PERSISTENT     
2ceb0 20 20 20 20 20 20 20 20 20 30 78 30 31 0a 23 64           0x01.#d
2cec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45  efine SQLITE_PRE
2ced0 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20  PARE_NORMALIZE  
2cee0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
2cef0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2cf00 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42  _PREPARE_NO_VTAB
2cf10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cf20 20 30 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x04../*.** CAP
2cf30 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2cf40 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2cf50 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2cf60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2cf70 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2cf80 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2cf90 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2cfa0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2cfb0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2cfc0 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75  statement, it mu
2cfd0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
2cfe0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
2cff0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
2d000 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
2d010 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f  ese routines.  O
2d020 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  r, in other word
2d030 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  s, these routine
2d040 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75  s.** are constru
2d050 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70  ctors for the [p
2d060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d070 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  t] object..**.**
2d080 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72   The preferred r
2d090 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73  outine to use is
2d0a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d0b0 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a  e_v2()].  The.**
2d0c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d0d0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  e()] interface i
2d0e0 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f  s legacy and sho
2d0f0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2d100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2d110 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e  are_v3()] has an
2d120 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67   extra "prepFlag
2d130 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69  s" option that i
2d140 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70  s used.** for sp
2d150 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a  ecial purposes..
2d160 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66  **.** The use of
2d170 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72   the UTF-8 inter
2d180 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72  faces is preferr
2d190 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75  ed, as SQLite cu
2d1a0 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20  rrently.** does 
2d1b0 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e  all parsing usin
2d1c0 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54  g UTF-8.  The UT
2d1d0 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2d1e0 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
2d1f0 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  as a convenience
2d200 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2d210 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79  terfaces work by
2d220 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a   converting the.
2d230 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e  ** input text in
2d240 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69  to UTF-8, then i
2d250 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72  nvoking the corr
2d260 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20  esponding UTF-8 
2d270 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2d280 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
2d290 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
2d2a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d2b0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
2d2c0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
2d2d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2d2e0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2d2f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2d300 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
2d310 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2d320 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
2d330 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2d340 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
2d350 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
2d360 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
2d370 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
2d380 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2d390 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
2d3a0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
2d3b0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
2d3c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2d3d0 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f  pare(), sqlite3_
2d3e0 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a  prepare_v2(),.**
2d3f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2d400 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74  pare_v3().** int
2d410 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2d420 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2d430 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69  repare16(), sqli
2d440 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d450 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2d460 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2d470 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ) use UTF-16..**
2d480 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
2d490 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
2d4a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
2d4b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
2d4c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
2d4d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
2d4e0 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
2d4f0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
2d500 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2d510 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
2d520 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
2d530 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
2d540 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
2d550 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
2d560 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
2d570 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
2d580 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
2d590 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
2d5a0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
2d5b0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
2d5c0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
2d5d0 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
2d5e0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
2d5f0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
2d600 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d610 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
2d620 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
2d630 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
2d640 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
2d650 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
2d660 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
2d670 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
2d680 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2d690 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
2d6a0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
2d6b0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
2d6c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2d6d0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
2d6e0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
2d6f0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
2d700 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
2d710 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
2d720 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
2d730 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
2d740 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
2d750 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
2d760 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
2d770 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
2d780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2d790 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
2d7a0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
2d7b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
2d7c0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
2d7d0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
2d7e0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
2d7f0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
2d800 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
2d810 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
2d820 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
2d830 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
2d840 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
2d850 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
2d860 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
2d870 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
2d880 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
2d890 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
2d8a0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
2d8b0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2d8c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d8d0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
2d8e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2d8f0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
2d900 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
2d910 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
2d920 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2d930 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
2d940 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2d950 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
2d960 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
2d970 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2d980 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2d990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d9a0 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v2(), sqlite3_pr
2d9b0 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69  epare_v3(), sqli
2d9c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d9d0 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2d9e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2d9f0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2da00 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2da10 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2da20 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20  s..** The older 
2da30 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69  interfaces (sqli
2da40 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
2da50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2da60 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65  e16()).** are re
2da70 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
2da80 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2da90 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2daa0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2dab0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58  ..** ^In the "vX
2dac0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2dad0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2dae0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2daf0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2db00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2db10 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2db20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2db30 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2db40 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2db50 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2db60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2db70 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2db80 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2db90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2dba0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2dbb0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2dbc0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2dbd0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2dbe0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2dbf0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2dc00 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2dc10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2dc20 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2dc30 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2dc40 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2dc50 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2dc60 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2dc70 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2dc80 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2dc90 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2dca0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2dcb0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2dcc0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2dcd0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2dce0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2dcf0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2dd00 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2dd10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2dd20 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2dd30 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2dd40 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2dd50 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2dd60 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2dd70 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2dd80 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2dd90 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2dda0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2ddb0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2ddc0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2ddd0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2dde0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2ddf0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2de00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2de10 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2de20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2de30 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2de40 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2de50 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2de60 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2de70 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2de80 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2de90 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2dea0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2deb0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2dec0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2ded0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2dee0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2def0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2df00 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2df10 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2df20 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2df30 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2df40 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2df50 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2df60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2df70 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2df80 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2df90 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2dfa0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2dfb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2dfc0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2dfd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2dfe0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2dff0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2e000 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2e010 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2e020 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2e030 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2e040 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2e050 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2e060 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2e070 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2e080 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2e090 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2e0a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2e0b0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2e0c0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2e0d0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2e0e0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2e0f0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2e100 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2e110 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2e120 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2e130 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2e140 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2e150 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2e160 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   </ol>.**.** <p>
2e170 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  ^sqlite3_prepare
2e180 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72  _v3() differs fr
2e190 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  om sqlite3_prepa
2e1a0 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20  re_v2() only in 
2e1b0 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78  having.** the ex
2e1c0 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61  tra prepFlags pa
2e1d0 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69  rameter, which i
2e1e0 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f  s a bit array co
2e1f0 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f  nsisting of zero
2e200 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74   or.** more of t
2e210 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  he [SQLITE_PREPA
2e220 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51  RE_PERSISTENT|SQ
2e230 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20  LITE_PREPARE_*] 
2e240 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20  flags.  ^The.** 
2e250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e260 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
2e270 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65  orks exactly the
2e280 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
2e290 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2e2a0 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65   with a zero pre
2e2b0 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2e2c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e2d0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2e2e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2e2f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2e300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e310 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2e320 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2e330 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2e340 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2e350 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2e360 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2e370 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2e380 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2e390 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2e3a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2e3b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2e3c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2e3d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2e3e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2e3f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2e400 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2e410 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
2e420 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2e440 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2e450 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2e460 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2e470 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2e480 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2e490 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2e4a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2e4b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2e4c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2e4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2e4e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2e4f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2e500 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e510 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2e520 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2e530 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2e540 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2e550 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2e560 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v3(.  sqlite3 
2e570 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2e580 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2e590 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2e5a0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2e5b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2e5c0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2e5d0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2e5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e5f0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2e600 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2e610 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2e620 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2e630 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2e640 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2e650 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2e660 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2e670 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2e680 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2e690 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2e6a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2e6b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2e6c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2e6d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2e6e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
2e6f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e700 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e710 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2e730 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e740 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2e750 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2e760 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2e770 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2e780 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2e790 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2e7a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2e7b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2e7c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2e7d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2e7e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2e7f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2e800 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2e810 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2e820 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e830 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2e840 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e850 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2e860 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2e870 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2e880 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2e890 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2e8a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2e8b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2e8c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2e8d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2e8e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2e8f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2e900 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2e910 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2e920 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2e930 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2e940 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2e950 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2e960 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2e970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a  3_prepare16_v3(.
2e980 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e990 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2e9a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2e9b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2e9c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2e9d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2e9e0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2e9f0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ea00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ea10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ea20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ea30 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2ea40 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2ea50 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2ea60 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2ea70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ea80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ea90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2eaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2eab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2eac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ead0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2eae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2eaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eb00 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2eb10 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2eb20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2eb30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2eb40 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2eb50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2eb60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2eb70 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2eb80 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2eb90 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2eba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ebb0 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2ebc0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
2ebd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ebe0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2ebf0 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v3()],.** [sq
2ec00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ec10 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
2ec20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2ec30 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2ec40 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ec50 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2ec60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ec70 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2ec80 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2ec90 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2eca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ecb0 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2ecc0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2ecd0 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68  expanded..** ^Th
2ece0 65 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c  e sqlite3_normal
2ecf0 69 7a 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65  ized_sql(P) inte
2ed00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2ed10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
2ed20 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  -8.** string con
2ed30 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d  taining the norm
2ed40 61 6c 69 7a 65 64 20 53 51 4c 20 74 65 78 74 20  alized SQL text 
2ed50 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2ed60 65 6d 65 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a  ement P.  The.**
2ed70 20 73 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20   semantics used 
2ed80 74 6f 20 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53  to normalize a S
2ed90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  QL statement are
2eda0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2edb0 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63   subject.** to c
2edc0 68 61 6e 67 65 2e 20 20 41 74 20 61 20 6d 69 6e  hange.  At a min
2edd0 69 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61  imum, literal va
2ede0 6c 75 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70  lues will be rep
2edf0 6c 61 63 65 64 20 77 69 74 68 20 73 75 69 74 61  laced with suita
2ee00 62 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64  ble.** placehold
2ee10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ers..**.** ^(For
2ee20 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2ee30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ee40 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2ee50 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2ee60 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2ee70 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2ee80 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2ee90 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2eea0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2eeb0 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2eec0 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2eed0 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2eee0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2eef0 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2ef00 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2ef10 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2ef20 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2ef30 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2ef40 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ef60 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ef70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2ef80 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2ef90 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2efa0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2efb0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2efc0 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2efd0 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2efe0 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2eff0 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2f000 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2f010 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2f020 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2f030 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2f040 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2f050 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2f060 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2f070 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2f080 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2f090 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2f0a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2f0b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2f0c0 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2f0d0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2f0e0 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2f0f0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2f100 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 73  .** ^The strings
2f110 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2f120 69 74 65 33 5f 73 71 6c 28 50 29 20 61 6e 64 20  ite3_sql(P) and 
2f130 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2f140 65 64 5f 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65  ed_sql(P).** are
2f150 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2f160 74 65 20 61 6e 64 20 61 72 65 20 61 75 74 6f 6d  te and are autom
2f170 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77  atically freed w
2f180 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
2f190 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2f1a0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2f1b0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2f1c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2f1d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2f1e0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2f1f0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2f200 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2f210 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2f220 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2f230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2f240 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2f250 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2f260 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2f270 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2f280 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f290 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2f2a0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2f2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f2c0 74 6d 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  tmt);.const char
2f2d0 20 2a 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c   *sqlite3_normal
2f2e0 69 7a 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33  ized_sql(sqlite3
2f2f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2f300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f310 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
2f320 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
2f330 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
2f340 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
2f350 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2f360 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2f370 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
2f380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f390 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2f3a0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
2f3b0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
2f3c0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
2f3d0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
2f3e0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
2f3f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2f400 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2f410 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
2f420 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f430 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2f440 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
2f450 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
2f460 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2f470 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
2f480 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
2f490 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2f4a0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
2f4b0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
2f4c0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
2f4d0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
2f4e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f4f0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
2f500 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
2f510 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
2f520 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2f530 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
2f540 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
2f550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
2f560 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
2f570 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
2f580 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
2f590 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
2f5a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
2f5b0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
2f5c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2f5d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2f5e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2f5f0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
2f600 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2f610 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
2f620 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
2f630 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
2f640 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
2f650 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
2f660 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
2f670 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
2f680 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
2f690 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
2f6a0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
2f6b0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2f6c0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
2f6d0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
2f6e0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
2f6f0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
2f700 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2f710 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
2f720 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
2f730 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
2f740 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
2f750 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
2f760 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
2f770 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
2f780 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
2f790 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
2f7a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2f7b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2f7c0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
2f7d0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
2f7e0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
2f7f0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
2f800 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
2f810 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
2f820 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
2f830 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
2f840 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2f850 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
2f860 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  isk..** ^The sql
2f870 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f880 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ly() interface r
2f890 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20  eturns true for 
2f8a0 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a  [BEGIN] since.**
2f8b0 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20   [BEGIN] merely 
2f8c0 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c  sets internal fl
2f8d0 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45  ags, but the [BE
2f8e0 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49  GIN|BEGIN IMMEDI
2f8f0 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47  ATE] and.** [BEG
2f900 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49  IN|BEGIN EXCLUSI
2f910 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20  VE] commands do 
2f920 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 61  touch the databa
2f930 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c  se and so.** sql
2f940 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f950 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c  ly() returns fal
2f960 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d  se for those com
2f970 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  mands..*/.int sq
2f980 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2f990 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
2f9a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f9b0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
2f9c0 20 54 68 65 20 45 58 50 4c 41 49 4e 20 53 65 74   The EXPLAIN Set
2f9d0 74 69 6e 67 20 46 6f 72 20 41 20 50 72 65 70 61  ting For A Prepa
2f9e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2f9f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2fa00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2fa10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73   sqlite3_stmt_is
2fa20 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72  explain(S) inter
2fa30 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69  face returns 1 i
2fa40 66 20 74 68 65 0a 2a 2a 20 70 72 65 70 61 72 65  f the.** prepare
2fa50 64 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  d statement S is
2fa60 20 61 6e 20 45 58 50 4c 41 49 4e 20 73 74 61 74   an EXPLAIN stat
2fa70 65 6d 65 6e 74 2c 20 6f 72 20 32 20 69 66 20 74  ement, or 2 if t
2fa80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
2fa90 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49 4e 20  S is an EXPLAIN 
2faa0 51 55 45 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e  QUERY PLAN..** ^
2fab0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2fac0 5f 69 73 65 78 70 6c 61 69 6e 28 53 29 20 69 6e  _isexplain(S) in
2fad0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fae0 30 20 69 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20  0 if S is.** an 
2faf0 6f 72 64 69 6e 61 72 79 20 73 74 61 74 65 6d 65  ordinary stateme
2fb00 6e 74 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  nt or a NULL poi
2fb10 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
2fb20 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c  ite3_stmt_isexpl
2fb30 61 69 6e 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ain(sqlite3_stmt
2fb40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2fb50 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2fb60 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
2fb70 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
2fb80 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
2fb90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2fba0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2fbb0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2fbc0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2fbd0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2fbe0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2fbf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fc00 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2fc10 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2fc20 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2fc30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2fc40 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
2fc50 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
2fc60 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
2fc70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
2fc80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
2fc90 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
2fca0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2fcb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fcc0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2fcd0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2fce0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fcf0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2fd00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2fd10 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2fd20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2fd30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2fd40 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2fd50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fd60 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2fd70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2fd80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2fd90 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2fda0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2fdb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2fdc0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2fdd0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2fde0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2fdf0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2fe00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2fe10 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2fe20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2fe30 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2fe40 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2fe50 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2fe60 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2fe70 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2fe80 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2fe90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2fea0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2feb0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2fec0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2fed0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2fee0 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
2fef0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
2ff00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2ff10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ff20 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
2ff30 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
2ff40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
2ff50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ff60 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
2ff70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2ff80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
2ff90 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
2ffa0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
2ffb0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
2ffc0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
2ffd0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
2ffe0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
2fff0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
30000 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
30010 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
30020 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
30030 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
30040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
30050 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
30060 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
30070 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
30080 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
30090 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
300a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
300b0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
300c0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
300d0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
300e0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
300f0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
30100 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30110 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
30120 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
30130 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
30140 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
30150 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30160 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
30170 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
30180 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
30190 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
301a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
301b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
301c0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
301d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
301e0 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
301f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
30200 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
30210 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
30220 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
30230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30240 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
30250 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30260 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
30270 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
30280 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
30290 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
302a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
302b0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
302c0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
302d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
302e0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
302f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
30300 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
30310 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
30320 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
30330 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
30340 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
30350 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
30360 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
30370 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
30380 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
30390 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
303a0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
303b0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
303c0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
303d0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
303e0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
303f0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
30400 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
30410 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
30420 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
30430 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
30440 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
30450 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
30460 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
30470 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
30480 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
30490 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
304a0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
304b0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
304c0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
304d0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
304e0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
304f0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
30500 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
30510 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
30520 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
30530 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
30540 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
30550 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
30560 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
30570 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
30580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30590 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
305a0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
305b0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
305c0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
305d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
305e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
305f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
30600 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
30610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
30620 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
30630 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
30640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
30650 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
30660 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
30670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30680 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
30690 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72 67  y be used as arg
306a0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71  uments.** to [sq
306b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
306c0 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ue()], [sqlite3_
306d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61  bind_value()], a
306e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  nd.** [sqlite3_v
306f0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20  alue_dup()]..** 
30700 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30710 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
30720 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
30730 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
30740 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
30750 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30760 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
30770 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
30780 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ct sqlite3_value
30790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
307a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
307b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
307c0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
307d0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
307e0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
307f0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
30800 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
30810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
30820 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
30830 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
30840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
30850 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
30860 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
30870 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
30880 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30890 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
308a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
308b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
308c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
308d0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
308e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
308f0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
30900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30910 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
30920 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
30930 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30940 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
30950 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
30960 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
30970 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
30980 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
30990 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
309a0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
309b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
309c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
309d0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
309e0 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
309f0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
30a00 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
30a10 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
30a20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
30a30 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
30a40 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
30a50 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
30a60 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
30a70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
30a80 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
30a90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
30aa0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
30ab0 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
30ac0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30ad0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
30ae0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
30af0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
30b00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
30b10 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
30b20 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
30b30 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
30b40 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
30b50 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
30b60 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
30b70 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
30b80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
30b90 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
30ba0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
30bb0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
30bc0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
30bd0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
30be0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
30bf0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
30c00 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
30c10 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
30c20 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
30c30 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
30c40 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
30c50 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
30c60 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
30c70 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
30c80 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
30c90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
30ca0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
30cb0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
30cc0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
30cd0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
30ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30cf0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30d00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
30d10 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
30d20 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
30d30 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
30d40 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
30d50 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
30d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30d70 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
30d80 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
30d90 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
30da0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
30db0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
30dc0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
30dd0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
30de0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
30df0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
30e00 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
30e10 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
30e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
30e30 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
30e40 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
30e50 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
30e60 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
30e70 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
30e80 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
30e90 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
30ea0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
30eb0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
30ec0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
30ed0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
30ee0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
30ef0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
30f00 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
30f10 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
30f20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
30f30 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
30f40 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
30f50 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
30f60 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
30f70 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
30f80 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
30f90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
30fa0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
30fb0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
30fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
30fd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
30fe0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
30ff0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
31000 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
31010 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
31020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
31030 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
31040 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
31050 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
31060 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
31070 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
31080 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31090 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
310a0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
310b0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
310c0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
310d0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
310e0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
310f0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
31100 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
31110 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
31120 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
31130 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
31140 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
31150 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
31160 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
31170 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
31180 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
31190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
311a0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
311b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
311c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
311d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
311e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
311f0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
31200 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
31210 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
31220 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
31230 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
31240 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
31250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
31260 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
31270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
31290 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
312a0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
312b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
312c0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
312d0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
312e0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
312f0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
31300 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
31310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31320 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
31330 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
31340 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
31350 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
31360 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
31370 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
31380 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
31390 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
313a0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
313b0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
313c0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
313d0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
313e0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
313f0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
31400 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
31410 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31420 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
31430 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
31440 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
31450 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
31460 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
31470 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
31480 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
31490 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
314a0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
314b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
314c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
314d0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
314e0 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
314f0 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
31500 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
31510 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
31520 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
31530 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
31540 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
31550 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
31560 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
31570 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
31580 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
31590 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
315a0 6c 6c 20 74 6f 20 74 68 65 20 62 69 6e 64 20 41  ll to the bind A
315b0 50 49 20 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63  PI fails,.** exc
315c0 65 70 74 20 74 68 65 20 64 65 73 74 72 75 63 74  ept the destruct
315d0 6f 72 20 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64  or is not called
315e0 20 69 66 20 74 68 65 20 74 68 69 72 64 20 70 61   if the third pa
315f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c  rameter is a NUL
31600 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
31610 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
31620 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
31630 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
31640 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
31650 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
31660 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
31670 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
31680 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31690 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
316a0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
316b0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
316c0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
316d0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
316e0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
316f0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
31700 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
31710 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
31720 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
31730 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
31740 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
31750 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
31760 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
31770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
31780 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
31790 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
317a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
317b0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
317c0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
317d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
317e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
317f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
31800 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
31810 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
31820 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
31830 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
31840 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
31850 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
31860 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
31870 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
31880 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
31890 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
318a0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
318b0 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
318c0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
318d0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
318e0 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
318f0 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
31900 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
31910 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
31920 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
31930 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
31940 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
31950 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
31960 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
31970 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
31980 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
31990 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
319a0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
319b0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
319c0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
319d0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
319e0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
319f0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
31a00 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
31a10 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
31a20 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
31a30 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
31a40 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
31a50 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
31a60 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
31a70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
31a80 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
31a90 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
31aa0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
31ab0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
31ac0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
31ad0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
31ae0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
31af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
31b00 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c  ind_pointer(S,I,
31b10 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  P,T,D) routine c
31b20 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70  auses the I-th p
31b30 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b  arameter in.** [
31b40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31b50 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e  nt] S to have an
31b60 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55   SQL value of NU
31b70 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20  LL, but to also 
31b80 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  be.** associated
31b90 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65   with the pointe
31ba0 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20  r P of type T.  
31bb0 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ^D is either a N
31bc0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a  ULL pointer or.*
31bd0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
31be0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
31bf0 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c  tion for P. ^SQL
31c00 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
31c10 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  the.** destructo
31c20 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
31c30 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20  e argument of P 
31c40 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73  when it is finis
31c50 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20  hed using.** P. 
31c60 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72   The T parameter
31c70 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61   should be a sta
31c80 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66  tic string, pref
31c90 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a  erably a string.
31ca0 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20  ** literal. The 
31cb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
31cc0 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69  nter() routine i
31cd0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
31ce0 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e   [pointer passin
31cf0 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64  g interface] add
31d00 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e  ed for SQLite 3.
31d10 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  20.0..**.** ^If 
31d20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
31d30 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
31d40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
31d50 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
31d60 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
31d70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31d80 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
31d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31da0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
31db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
31dc0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
31dd0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
31de0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
31df0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
31e00 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
31e10 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
31e20 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
31e30 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
31e40 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
31e50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31e60 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
31e70 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
31e80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
31e90 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
31ea0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
31eb0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
31ec0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
31ed0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
31ee0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
31ef0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
31f00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
31f10 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
31f20 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
31f30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
31f40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
31f50 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
31f60 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
31f70 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
31f80 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
31f90 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
31fa0 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
31fb0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
31fc0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
31fd0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
31fe0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
31ff0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
32000 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
32010 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
32020 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
32030 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
32040 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
32050 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
32060 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
32070 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
32080 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
32090 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
320a0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
320b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
320c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
320d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
320e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
320f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
32100 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
32110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32120 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
32130 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32140 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
32150 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
32160 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
32170 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
32180 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32190 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
321a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
321b0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
321c0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
321d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
321e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
321f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
32200 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
32210 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
32220 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
32230 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
32240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
32250 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
32260 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
32270 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32280 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
32290 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
322a0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
322b0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
322c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
322d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
322e0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
322f0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
32300 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
32310 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
32320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32330 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32340 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32350 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
32360 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
32370 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
32380 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
32390 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
323a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
323b0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
323c0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
323d0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
323e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
323f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
32400 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
32410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32420 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32430 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33  _pointer(sqlite3
32440 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69  _stmt*, int, voi
32450 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  d*, const char*,
32460 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
32480 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
32490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
324a0 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt n);.int sqlit
324b0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
324c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
324d0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75  , int, sqlite3_u
324e0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
324f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
32500 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
32510 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
32520 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32530 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
32540 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
32550 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
32560 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
32570 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
32580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32590 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
325a0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
325b0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
325c0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
325d0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
325e0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
325f0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
32600 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
32610 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
32620 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
32630 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
32640 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
32650 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
32660 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
32670 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
32680 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
32690 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
326a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
326b0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
326c0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
326d0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
326e0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
326f0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
32700 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
32710 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
32720 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
32730 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
32740 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
32750 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
32760 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
32770 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
32780 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
32790 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
327a0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
327b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
327c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
327d0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
327e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
327f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
32800 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
32810 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
32820 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
32830 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32840 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32850 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
32860 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
32870 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
32880 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
32890 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
328a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
328b0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
328c0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
328d0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
328e0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
328f0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
32900 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
32910 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
32920 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
32930 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
32940 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
32950 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
32960 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
32970 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
32980 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
32990 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
329a0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
329b0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
329c0 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
329d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
329e0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
329f0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
32a00 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
32a10 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
32a20 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
32a30 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
32a40 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
32a50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
32a60 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
32a70 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
32a80 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
32a90 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
32aa0 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
32ab0 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
32ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
32ad0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
32ae0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
32af0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
32b00 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
32b10 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
32b20 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
32b30 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
32b40 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
32b50 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
32b60 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
32b70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
32b80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
32b90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
32ba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
32bb0 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a  are16_v3()]..**.
32bc0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
32bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
32be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
32bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
32c00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
32c10 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
32c20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32c30 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
32c40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
32c50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32c60 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
32c70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
32c80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32c90 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
32ca0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
32cb0 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
32cc0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32cd0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
32ce0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
32cf0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
32d00 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
32d10 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
32d20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
32d30 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
32d40 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
32d50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32d60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
32d70 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
32d80 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
32d90 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
32da0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
32db0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
32dc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
32dd0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
32de0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
32df0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
32e00 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
32e10 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
32e20 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
32e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32e40 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  6_v2()] or.** [s
32e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32e60 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
32e70 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32e80 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
32e90 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
32ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
32eb0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
32ec0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
32ed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32ee0 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  name()]..*/.int 
32ef0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
32f00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
32f10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
32f20 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
32f30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f40 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
32f50 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
32f60 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
32f70 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32f80 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
32f90 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
32fa0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
32fb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32fc0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
32fd0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
32fe0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
32ff0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
33000 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
33010 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
33020 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
33030 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
33040 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
33050 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
33060 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
33070 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
33080 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
33090 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
330a0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
330b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
330c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
330d0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
330e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
330f0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
33100 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
33110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33120 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ]. ^If this rout
33130 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ine returns 0, t
33140 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a  hat means the .*
33150 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33160 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e  ement] returns n
33170 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  o data (for exam
33180 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
33190 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a  ..** ^However, j
331a0 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73  ust because this
331b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
331c0 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
331d0 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d  er does not.** m
331e0 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20  ean that one or 
331f0 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74  more rows of dat
33200 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  a will be return
33210 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73  ed.  ^A SELECT s
33220 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c  tatement.** will
33230 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70   always have a p
33240 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f  ositive sqlite3_
33250 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62  column_count() b
33260 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ut depending on 
33270 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  the.** WHERE cla
33280 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
33290 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f  and the table co
332a0 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20  ntent, it might 
332b0 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a  return no rows..
332c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
332d0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
332e0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
332f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
33300 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
33310 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
33320 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
33330 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
33340 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
33350 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
33370 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
33380 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
33390 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
333a0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
333b0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
333c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
333d0 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
333e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
333f0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
33400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
33410 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
33420 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
33430 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
33440 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
33450 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
33460 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
33470 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
33480 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
33490 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
334a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
334b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
334c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
334d0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
334e0 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
334f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
33500 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
33510 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
33520 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
33530 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
33540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
33550 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
33560 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
33570 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
33580 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
33590 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
335a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
335b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
335c0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
335d0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
335e0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
335f0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
33600 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
33610 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
33620 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
33630 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
33640 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33650 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
33660 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
33670 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
33680 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
33690 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
336a0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
336b0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
336c0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
336d0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
336e0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
336f0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
33700 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
33710 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
33720 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
33730 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
33740 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
33750 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
33760 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
33770 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
33780 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
33790 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
337a0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
337b0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
337c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
337d0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
337e0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
337f0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
33800 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
33810 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
33820 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
33830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33840 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
33850 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
33860 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33870 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
33880 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33890 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
338a0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
338b0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
338c0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
338d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
338e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
338f0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
33900 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
33910 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
33920 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
33930 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
33940 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
33950 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
33960 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
33970 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
33980 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
33990 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
339a0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
339b0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
339c0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
339d0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
339e0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
339f0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
33a00 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
33a10 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
33a20 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
33a30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
33a40 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
33a50 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
33a60 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
33a70 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
33a80 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
33a90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
33aa0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
33ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33ac0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
33ad0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
33ae0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
33af0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
33b00 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
33b10 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
33b20 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
33b30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33b40 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
33b50 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
33b60 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
33b70 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
33b80 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
33b90 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
33ba0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
33bb0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
33bc0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
33bd0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
33be0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
33bf0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
33c00 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
33c10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
33c20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
33c30 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
33c40 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
33c50 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
33c60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
33c70 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
33c80 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
33c90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
33ca0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
33cb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
33cc0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
33cd0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
33ce0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
33cf0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
33d00 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
33d10 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
33d20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
33d30 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
33d40 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
33d50 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
33d60 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
33d70 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
33d80 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
33d90 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
33da0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
33db0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
33dc0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
33dd0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
33de0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
33df0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
33e00 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
33e10 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
33e20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
33e30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
33e40 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
33e50 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
33e60 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
33e70 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
33e80 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
33e90 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
33ea0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
33eb0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
33ec0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
33ed0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
33ee0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
33ef0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
33f00 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
33f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
33f20 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
33f30 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
33f40 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
33f50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
33f60 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
33f70 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
33f80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
33f90 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
33fa0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
33fb0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
33fc0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
33fd0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
33fe0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
33ff0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
34000 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
34010 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
34020 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
34030 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34040 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
34050 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
34060 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
34070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
34080 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
34090 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
340a0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
340b0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
340c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
340d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
340e0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
340f0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
34100 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
34110 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
34120 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34130 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
34140 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
34150 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
34170 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
34180 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34190 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
341a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
341b0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
341c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
341d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
341e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
341f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
34200 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
34210 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34220 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
34230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
34240 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
34260 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
34270 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
34280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34290 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
342a0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
342b0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
342c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
342d0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
342e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
342f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34300 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
34310 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
34320 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
34330 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
34340 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
34350 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
34360 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
34370 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
34380 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
34390 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
343a0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
343b0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
343c0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
343d0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
343e0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
343f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
34400 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
34410 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
34420 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
34430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34440 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
34450 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
34460 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
34470 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
34480 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
34490 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
344a0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
344b0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
344c0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
344d0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
344e0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
344f0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
34500 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
34510 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
34520 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
34530 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
34540 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
34550 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
34560 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
34570 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
34580 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
34590 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
345a0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
345b0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
345c0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
345d0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
345e0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
345f0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
34600 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
34610 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
34620 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
34630 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
34640 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
34650 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
34660 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
34670 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
34680 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
34690 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
346a0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
346b0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
346c0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
346d0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
346e0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
346f0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
34700 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
34710 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
34720 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
34730 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34740 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
34750 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
34760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
34780 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
34790 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
347a0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
347b0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
347c0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
347d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
347e0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
347f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34800 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
34810 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a  d using any of.*
34820 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
34830 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
34840 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
34850 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
34860 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f  re16_v2()],.** o
34870 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
34880 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e  re16_v3()] or on
34890 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
348a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
348b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
348c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
348d0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
348e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
348f0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
34900 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
34910 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
34920 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
34930 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
34940 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
34950 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
34960 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
34970 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
34980 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
34990 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
349a0 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20   the newer "vX" 
349b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73  interfaces.** [s
349c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
349d0 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
349e0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
349f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
34a00 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v3()],.** [sqli
34a10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
34a20 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
34a30 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
34a40 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
34a50 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
34a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
34a70 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
34a80 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22   the.** new "vX"
34a90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
34aa0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
34ab0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
34ac0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
34ad0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
34ae0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
34af0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
34b00 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
34b10 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
34b20 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
34b30 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
34b40 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
34b50 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
34b60 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
34b70 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
34b80 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
34b90 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
34ba0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
34bb0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
34bc0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
34bd0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
34be0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
34bf0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
34c00 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
34c10 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
34c20 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
34c30 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
34c40 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
34c50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
34c60 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
34c70 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
34c80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
34c90 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
34ca0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
34cb0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
34cc0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
34cd0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
34ce0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
34cf0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
34d00 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
34d10 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
34d20 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
34d30 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
34d40 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
34d50 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
34d60 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
34d70 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
34d90 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
34da0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
34db0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
34dc0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
34dd0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
34de0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
34df0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
34e00 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
34e10 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
34e20 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
34e30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
34e40 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
34e50 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
34e60 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
34e70 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
34e80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
34e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
34ea0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
34eb0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
34ec0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
34ed0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
34ee0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
34ef0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
34f00 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
34f10 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
34f20 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
34f30 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
34f40 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
34f50 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
34f60 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
34f70 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
34f80 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
34f90 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
34fa0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
34fb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
34fc0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
34fd0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
34fe0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
34ff0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
35000 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
35010 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
35020 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
35030 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
35040 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
35050 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
35060 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
35070 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
35080 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
35090 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
350a0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
350b0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
350c0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
350d0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
350e0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
350f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
35100 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
35110 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
35120 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
35130 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35140 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
35150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35160 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
35170 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
35180 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
35190 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
351a0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
351b0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
351c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
351d0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
351e0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
351f0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
35200 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
35210 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
35220 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
35230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35240 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
35250 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
35260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
35270 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
35280 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
35290 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
352a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
352b0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
352c0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
352d0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
352e0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
352f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35300 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
35310 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
35320 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
35330 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
35340 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
35350 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
35360 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
35370 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
35380 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
35390 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
353a0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
353b0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
353c0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
353d0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
353e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
353f0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
35400 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
35410 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
35420 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
35430 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
35440 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
35450 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
35460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35470 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
35480 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
35490 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
354a0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
354b0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
354c0 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
354d0 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
354e0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
354f0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
35500 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
35510 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
35520 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
35530 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
35540 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
35550 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
35560 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
35570 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
35580 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
35590 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
355a0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
355b0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
355c0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
355d0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
355e0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
355f0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
35600 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
35610 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
35620 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
35630 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
35640 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
35650 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
35660 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
35670 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
35680 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
35690 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
356a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
356b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
356c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
356d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
356e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
356f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
35700 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
35710 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
35720 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
35730 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
35740 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
35750 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
35760 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
35770 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
35780 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
35790 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
357a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
357b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
357c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
357d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
357e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
357f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
35800 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
35810 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
35820 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
35830 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
35840 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
35850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35860 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v3()] or [sqli
35870 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35880 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
35890 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
358a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
358b0 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73  pare16_v3()] ins
358c0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
358d0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
358e0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
358f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
35900 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
35910 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
35920 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
35930 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
35940 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
35950 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
35960 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
35970 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
35980 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ces is recommend
35990 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
359a0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
359b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
359c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
359d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
359e0 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
359f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
35a00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
35a10 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
35a20 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
35a30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35a40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
35a50 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
35a60 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
35a70 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
35a80 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
35a90 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
35aa0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
35ab0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
35ac0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
35ad0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
35ae0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
35af0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
35b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
35b10 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
35b20 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
35b30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
35b40 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
35b50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
35b60 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
35b70 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
35b80 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
35b90 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
35ba0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
35bb0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
35bc0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
35bd0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
35be0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
35bf0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
35c00 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
35c10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
35c20 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
35c30 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
35c40 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
35c50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
35c60 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
35c70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
35c80 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
35c90 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
35ca0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
35cb0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
35cc0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
35cd0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
35ce0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
35cf0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
35d00 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
35d10 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
35d20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
35d40 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
35d50 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
35d60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
35d70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
35d80 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
35d90 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
35da0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
35db0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
35dc0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
35dd0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
35de0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
35df0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
35e00 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
35e10 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
35e20 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
35e30 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
35e40 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
35e50 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
35e60 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
35e70 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
35e80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
35e90 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
35ea0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
35eb0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
35ec0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
35ed0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
35ee0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
35ef0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
35f00 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
35f10 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
35f20 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
35f30 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
35f40 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
35f50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
35f60 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
35f70 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
35f80 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
35f90 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
35fa0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
35fb0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
35fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35fd0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
35fe0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
35ff0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
36000 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
36010 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
36020 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
36030 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
36040 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
36050 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
36060 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
36070 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
36080 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
36090 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
360a0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
360b0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
360c0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
360d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
360e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d  tmt.**.** <b>Sum
360f0 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c  mary:</b>.** <bl
36100 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20  ockquote><table 
36110 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64  border=0 cellpad
36120 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69  ding=0 cellspaci
36130 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ng=0>.** <tr><td
36140 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
36150 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26  mn_blob</b><td>&
36160 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65  rarr;<td>BLOB re
36170 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
36180 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36190 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e  n_double</b><td>
361a0 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72  &rarr;<td>REAL r
361b0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
361c0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
361d0 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72  mn_int</b><td>&r
361e0 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49  arr;<td>32-bit I
361f0 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a  NTEGER result.**
36200 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
36220 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36230 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52  d>64-bit INTEGER
36240 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
36250 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36260 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64  lumn_text</b><td
36270 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38  >&rarr;<td>UTF-8
36280 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20   TEXT result.** 
36290 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
362a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
362b0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
362c0 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65  d>UTF-16 TEXT re
362d0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
362e0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
362f0 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26  n_value</b><td>&
36300 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73  rarr;<td>The res
36310 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73  ult as an .** [s
36320 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70  qlite3_value|unp
36330 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36340 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
36350 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70  ** <tr><td>&nbsp
36360 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26  ;<td>&nbsp;<td>&
36370 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64  nbsp;.** <tr><td
36380 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
36390 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e  mn_bytes</b><td>
363a0 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f  &rarr;<td>Size o
363b0 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61  f a BLOB.** or a
363c0 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75   UTF-8 TEXT resu
363d0 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c  lt in bytes.** <
363e0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
363f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36400 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e  &nbsp;&nbsp;</b>
36410 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e  .** <td>&rarr;&n
36420 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69  bsp;&nbsp;<td>Si
36430 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20  ze of UTF-16.** 
36440 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a  TEXT in bytes.**
36450 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c  te3_column_type<
36470 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36480 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61  >Default.** data
36490 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
364a0 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f  lt.** </table></
364b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
364c0 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62  * <b>Details:</b
364d0 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  >.**.** ^These r
364e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
364f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
36500 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
36510 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
36520 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
36530 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
36540 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
36550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
36560 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
36570 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
36580 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
36590 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
365a0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
365b0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
365c0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
365d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
365e0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
365f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
36600 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
36610 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
36620 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
36630 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
36640 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
36650 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
36660 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
36670 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
36680 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
36690 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
366a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
366b0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
366c0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
366d0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
366e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
366f0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
36700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
36710 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
36720 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
36730 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
36740 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
36750 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
36760 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
36770 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36780 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36790 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
367a0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
367b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
367c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
367d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
367e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
367f0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
36800 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
36810 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
36820 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
36830 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
36840 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
36850 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
36860 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
36870 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
36880 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
36890 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
368a0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
368b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
368c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
368d0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
368e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
368f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
36900 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
36910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36920 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
36930 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
36940 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
36950 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
36960 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
36970 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
36980 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
36990 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
369a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
369b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
369c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
369d0 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28  six interfaces (
369e0 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20  _blob, _double, 
369f0 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74  _int, _int64, _t
36a00 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36  ext, and _text16
36a10 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e  ).** each return
36a20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20   the value of a 
36a30 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
36a40 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
36a50 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20   format.  If.** 
36a60 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
36a70 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c  n is not initial
36a80 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73  ly in the reques
36a90 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20  ted format (for 
36aa0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74  example,.** if t
36ab0 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73  he query returns
36ac0 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20   an integer but 
36ad0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
36ae0 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66  mn_text() interf
36af0 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74  ace.** is used t
36b00 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61  o extract the va
36b10 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74  lue) then an aut
36b20 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76  omatic type conv
36b30 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
36b40 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  med..**.** ^The 
36b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36b60 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
36b70 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
36b80 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
36b90 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
36ba0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
36bb0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
36bc0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
36bd0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
36be0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
36bf0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
36c00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
36c10 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
36c20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
36c30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
36c40 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  LL]..** The retu
36c50 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69  rn value of sqli
36c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
36c70 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ) can be used to
36c80 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a   decide which.**
36c90 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69   of the first si
36ca0 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  x interface shou
36cb0 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78  ld be used to ex
36cc0 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e  tract the column
36cd0 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76   value..** The v
36ce0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
36cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36d00 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
36d10 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a  eaningful if no.
36d20 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70  ** automatic typ
36d30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  e conversions ha
36d40 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20  ve occurred for 
36d50 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65  the value in que
36d60 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65  stion.  .** Afte
36d70 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
36d80 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20  ion, the result 
36d90 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  of calling sqlit
36da0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
36db0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
36dc0 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73  , though harmles
36dd0 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  s.  Future.** ve
36de0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
36df0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
36e00 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
36e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
36e20 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
36e30 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36e40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
36e50 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
36e60 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67  or a TEXT string
36e70 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
36e80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36e90 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
36ea0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36eb0 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20   interfaces can 
36ec0 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72  be used to deter
36ed0 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a  mine the size.**
36ee0 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   of that BLOB or
36ef0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
36f00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
36f10 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
36f20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
36f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36f40 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
36f50 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
36f60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
36f70 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
36f80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
36f90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
36fa0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
36fb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
36fc0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
36fd0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
36fe0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
36ff0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
37000 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
37010 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
37020 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
37030 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
37040 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
37050 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
37060 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
37070 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
37080 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
37090 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
370a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
370b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
370c0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
370d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
370e0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
370f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
37100 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
37110 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
37120 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
37130 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
37140 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
37150 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
37160 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
37170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37180 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
37190 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
371a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
371b0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
371c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
371d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
371e0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
371f0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
37200 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
37210 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
37220 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
37230 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
37240 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
37250 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
37260 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
37270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
37280 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
37290 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
372a0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
372b0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
372c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
372d0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
372e0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
372f0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
37300 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37310 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
37320 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
37330 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
37340 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
37350 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
37360 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
37370 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37380 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
37390 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
373a0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
373b0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
373c0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
373d0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
373e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
373f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37400 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
37410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37420 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
37430 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
37440 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
37450 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
37460 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
37470 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
37480 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
37490 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
374a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
374b0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
374c0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
374d0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
374e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
374f0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
37500 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
37510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
37520 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
37530 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
37540 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
37550 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
37560 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
37570 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
37580 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
37590 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
375a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
375b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
375c0 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
375d0 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
375e0 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
375f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
37600 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
37610 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
37620 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
37630 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
37640 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
37650 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
37660 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
37670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37680 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
37690 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
376a0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
376b0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
376c0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
376d0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
376e0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
376f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
37700 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
37710 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
37720 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
37730 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
37740 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
37750 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20   threadsafe..** 
37760 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74  Hence, the sqlit
37770 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
37780 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ) interface.** i
37790 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20  s normally only 
377a0 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68  useful within th
377b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
377c0 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61   of .** [applica
377d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
377e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b   functions] or [
377f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c  virtual tables],
37800 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74   not within.** t
37810 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61  op-level applica
37820 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a  tion code..**.**
37830 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69   The these routi
37840 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20  nes may attempt 
37850 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64  to convert the d
37860 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72  atatype of the r
37870 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65  esult..** ^For e
37880 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
37890 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
378a0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
378b0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
378c0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
378d0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
378e0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
378f0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
37900 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
37910 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
37920 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
37930 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
37940 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
37950 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
37960 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
37970 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
37980 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
37990 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
379a0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
379b0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
379c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
379d0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
379e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
379f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
37a00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
37a10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
37a20 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
37a30 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
37a40 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
37a50 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
37a60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
37a70 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
37a80 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
37a90 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
37aa0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
37ab0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
37ac0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
37ad0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
37ae0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
37af0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
37b00 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
37b10 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
37b20 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
37b30 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
37b40 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
37b50 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
37b60 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
37b70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
37b80 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
37b90 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
37ba0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
37bb0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
37bc0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
37bd0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
37be0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
37bf0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
37c00 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
37c10 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
37c20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
37c30 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
37c40 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
37c50 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
37c60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
37c70 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
37c80 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
37c90 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
37ca0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
37cb0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
37cc0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
37cd0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
37ce0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
37cf0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
37d00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
37d10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
37d20 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
37d30 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
37d40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
37d50 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
37d60 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
37d70 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
37d80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
37d90 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
37da0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
37db0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
37dc0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
37dd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
37de0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
37df0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
37e00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
37e10 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
37e20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
37e30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
37e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37e50 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
37e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37e70 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
37e80 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
37e90 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
37ea0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
37eb0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
37ec0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
37ed0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
37ee0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
37ef0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
37f00 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
37f10 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
37f20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
37f30 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
37f40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
37f50 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
37f60 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
37f70 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
37f80 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
37f90 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
37fa0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
37fb0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
37fc0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
37fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37fe0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
37ff0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
38000 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
38010 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
38020 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
38030 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
38040 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
38050 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
38060 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
38070 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
38080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
38090 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
380a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
380b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
380c0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
380d0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
380e0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
380f0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
38100 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
38110 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
38120 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
38130 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
38140 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
38150 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
38160 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
38170 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
38180 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
38190 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
381a0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
381b0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
381c0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
381d0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
381e0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
381f0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
38200 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
38210 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
38220 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
38230 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
38240 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
38250 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
38260 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
38270 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
38280 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
38290 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
382a0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
382b0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
382c0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
382d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
382e0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
382f0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
38300 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
38310 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
38320 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
38330 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
38340 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
38350 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
38360 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
38370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
38380 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
38390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
383a0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
383b0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
383c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
383d0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
383e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
383f0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
38400 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
38410 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
38420 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
38430 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
38440 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
38450 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
38460 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
38470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
38480 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
38490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
384a0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
384b0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
384c0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
384d0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
384e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
384f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
38500 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
38510 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
38520 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
38530 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
38540 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
38550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
38560 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
38570 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
38580 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
38590 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
385a0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
385b0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
385c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
385d0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
385e0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
385f0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
38600 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
38610 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
38620 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
38630 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
38640 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
38650 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
38660 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
38670 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
38680 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
38690 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69  not pass the poi
386a0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
386b0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
386c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
386d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
386e0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
386f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
38700 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ree()]..**.** As
38710 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 69 6e 70   long as the inp
38720 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ut parameters ar
38730 65 20 63 6f 72 72 65 63 74 2c 20 74 68 65 73 65  e correct, these
3