/ Hex Artifact Content
Login

Artifact a95e2ac3a11c2d44faf18700c5ecc8beffc1409a0d21d8b855f1821469dd32c1:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69  underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74  lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65  s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65  s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65  n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51  bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61  _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65  C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72   is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a  to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69   underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54   file handle.  T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74  his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61   pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74   and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c  he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ue there..**.** 
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  de.  .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53  opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a  QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20  iptor is placed 
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20  in "batch write 
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20  mode", which.** 
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71  means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65  tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a  ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74  ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54   the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53  TOMIC_WRITE].  S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64  ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61  o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65  tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a  LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73  * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45  uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72  MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c  ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43  osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b  C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20   make.** no VFS 
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20  interface calls 
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20  ite3_file] file 
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78  descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74  cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74  o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c  hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f  be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73  mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65   the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65  .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d  nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73  mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a  tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c  t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20  ol takes.** the 
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20  te mode so that 
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54  MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63  _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a  auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69  ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73  nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20  IC_WRITE] to be 
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  rolled back..** 
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72  ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c  ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74  e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20   of batch write 
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20  mode.** so that 
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e  are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51   never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75  C_WRITE]..** </u
ccc0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
ccd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
cce0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
ccf0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
cd00: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
cd10: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
cd20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
cd30: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
cd40: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
cd50: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
cd60: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
cd70: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
cd80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
cd90: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
cda0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
cdb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cdc0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
cdd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
cde0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cdf0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
ce00: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
ce10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ce20: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
ce30: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
ce40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ce50: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
ce60: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ce80: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
ce90: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ceb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
cec0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
ced0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cee0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
cef0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
cf00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
cf10: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
cf20: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
cf30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
cf40: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
cf50: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
cf60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
cf70: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
cf80: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
cf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
cfa0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
cfb0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
cfc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
cfd0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cfe0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
cff0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
d000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d010: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
d020: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d030: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
d040: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
d050: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
d060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d070: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d080: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
d090: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
d0a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d0b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
d0c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
d0d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d0e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
d0f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
d100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d110: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
d120: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
d130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d140: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
d150: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
d160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d170: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
d180: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
d190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d1a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
d1b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
d1c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d1d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
d1e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
d1f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d200: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
d210: 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65        30.#define
d220: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
d230: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
d240: 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20       31.#define 
d250: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
d260: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
d270: 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
d280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
d290: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
d2a0: 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63  E  33../* deprec
d2b0: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
d2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
d2d0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d2e0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d2f0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
d300: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
d310: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
d320: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d330: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
d340: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d350: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
d360: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
d370: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
d380: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
d390: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
d3a0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
d3b0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
d3c0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
d3d0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
d3e0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
d3f0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
d400: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
d410: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
d420: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
d430: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
d440: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
d450: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
d460: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
d470: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
d480: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
d490: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
d4a0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
d4b0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
d4c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
d4d0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
d4e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
d4f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
d500: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
d510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
d520: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  adable Extension
d530: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70   Thunk.**.** A p
d540: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70  ointer to the op
d550: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69  aque sqlite3_api
d560: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74  _routines struct
d570: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ure is passed as
d580: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
d590: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79  rameter to entry
d5a0: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64   points of [load
d5b0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d  able extensions]
d5c0: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63  .  This.** struc
d5d0: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70  ture must be typ
d5e0: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20  edefed in order 
d5f0: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63  to work around c
d600: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
d610: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74  .** on some plat
d620: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  forms..*/.typede
d630: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d640: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71  _api_routines sq
d650: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d660: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  es;../*.** CAPI3
d670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
d680: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
d690: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
d6a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
d6b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
d6c0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d6d0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
d6e0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
d6f0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
d700: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
d710: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
d720: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
d730: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
d740: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d750: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
d760: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
d770: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
d780: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
d790: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46  on..**.** The VF
d7a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  S interface is s
d7b0: 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65  ometimes extende
d7c0: 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20  d by adding new 
d7d0: 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20  methods onto.** 
d7e0: 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74  the end.  Each t
d7f0: 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78 74 65  ime such an exte
d800: 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68  nsion occurs, th
d810: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
d820: 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  .** is increment
d830: 65 64 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ed.  The iVersio
d840: 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65 64 20  n value started 
d850: 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53  out as 1 in.** S
d860: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33  QLite [version 3
d870: 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .5.0] on [dateof
d880: 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e  :3.5.0], then in
d890: 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20  creased to 2.** 
d8a0: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
d8b0: 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b  sion 3.7.0] on [
d8c0: 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61  dateof:3.7.0], a
d8d0: 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65  nd then increase
d8e0: 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53  d.** to 3 with S
d8f0: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33  QLite [version 3
d900: 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .7.6] on [dateof
d910: 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69  :3.7.6].  Additi
d920: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d  onal fields.** m
d930: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d940: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  o the sqlite3_vf
d950: 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65  s object and the
d960: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a   iVersion value.
d970: 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20  ** may increase 
d980: 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20  again in future 
d990: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
d9a0: 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  te..** Note that
d9b0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
d9c0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
d9d0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
d9e0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
d9f0: 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51  ition from.** SQ
da00: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
da10: 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e  5.9] to [version
da20: 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.6.0] on [date
da30: 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64  of:3.6.0].** and
da40: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
da50: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20  n field was not 
da60: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
da70: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
da80: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
da90: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
daa0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
dab0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
dac0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
dad0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
dae0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
daf0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
db00: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
db10: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
db20: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
db30: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
db40: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
db50: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
db60: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
db70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
db80: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
db90: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
dba0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
dbb0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
dbc0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
dbd0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
dbe0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
dbf0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
dc00: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
dc10: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
dc20: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
dc30: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
dc40: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
dc50: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
dc60: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
dc70: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
dc80: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
dc90: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
dca0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
dcb0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
dcc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
dcd0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
dce0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
dcf0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
dd00: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
dd10: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
dd20: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
dd30: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
dd40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
dd50: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
dd60: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
dd70: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
dd80: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
dd90: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
dda0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
ddb0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
ddc0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
ddd0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
dde0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
ddf0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
de00: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
de10: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
de20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
de30: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
de40: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
de50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
de60: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
de70: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
de80: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
de90: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
dea0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
deb0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
dec0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
ded0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
dee0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
def0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
df00: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
df10: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
df20: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
df30: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
df40: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
df50: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
df60: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
df70: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
df80: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
df90: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
dfa0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
dfb0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
dfc0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
dfd0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
dfe0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
dff0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
e000: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
e010: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
e020: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
e030: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
e040: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
e050: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
e060: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
e070: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
e080: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
e090: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
e0a0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
e0b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
e0c0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
e0d0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
e0e0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
e0f0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
e100: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
e110: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e120: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
e130: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
e140: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
e150: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
e160: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
e170: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e180: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
e190: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
e1a0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
e1b0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
e1c0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
e1d0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
e1e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
e1f0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
e200: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
e210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
e220: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
e230: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
e240: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
e250: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
e260: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
e270: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
e280: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
e290: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
e2a0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
e2b0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
e2c0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e2d0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
e2e0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
e2f0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
e300: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
e310: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
e320: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e330: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e340: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
e350: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
e360: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
e370: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
e380: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e390: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e3a0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
e3b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
e3c0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
e3d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e3e0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
e3f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e400: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
e410: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e420: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
e430: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e440: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
e450: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e460: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
e470: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
e480: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e490: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
e4a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
e4b0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
e4c0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
e4d0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
e4e0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
e4f0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
e500: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
e510: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
e520: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
e530: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
e540: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
e550: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
e560: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
e570: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
e580: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
e590: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
e5a0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
e5b0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
e5c0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
e5d0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
e5e0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
e5f0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
e600: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
e610: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
e620: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
e630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
e640: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
e650: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
e660: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
e670: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
e680: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
e690: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
e6a0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
e6b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
e6c0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
e6d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
e6e0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
e6f0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
e700: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e710: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
e720: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e730: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
e740: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
e750: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
e760: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e770: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
e780: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
e790: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
e7a0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
e7b0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
e7c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e7d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
e7e0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
e7f0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
e800: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
e810: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
e820: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
e830: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
e840: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e850: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
e860: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
e870: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
e880: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
e890: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e8a0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
e8b0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
e8c0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
e8d0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
e8e0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
e8f0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
e900: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
e910: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e920: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
e930: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
e940: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
e950: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
e960: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
e970: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
e980: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
e990: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
e9a0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
e9b0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
e9c0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
e9d0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
e9e0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
e9f0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
ea00: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
ea10: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
ea20: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
ea30: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
ea40: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
ea50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
ea60: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
ea70: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
ea80: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
ea90: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
eaa0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
eab0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
eac0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
ead0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
eae0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
eaf0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
eb00: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
eb10: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
eb20: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
eb30: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
eb40: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
eb50: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
eb60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
eb70: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
eb80: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
eb90: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
eba0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
ebb0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
ebc0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
ebd0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
ebe0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
ebf0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
ec00: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
ec10: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
ec20: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
ec30: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
ec40: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
ec50: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
ec60: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
ec70: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ec80: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
ec90: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
eca0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
ecb0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
ecc0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
ecd0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
ece0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
ecf0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
ed00: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
ed10: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ed20: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
ed30: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
ed40: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
ed50: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
ed60: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
ed70: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
ed80: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
ed90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
eda0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
edb0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
edc0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
edd0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
ede0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
edf0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
ee00: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
ee10: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
ee20: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
ee30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
ee40: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
ee50: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
ee60: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
ee70: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
ee80: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
ee90: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
eea0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
eeb0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
eec0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
eed0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
eee0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
eef0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
ef00: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
ef10: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
ef20: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
ef30: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
ef40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
ef50: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
ef60: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
ef70: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
ef80: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
ef90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
efa0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
efb0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
efc0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
efd0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
efe0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
eff0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
f000: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
f010: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
f020: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
f030: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
f040: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
f050: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
f060: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
f070: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
f080: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
f090: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
f0a0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
f0b0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
f0c0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
f0d0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
f0e0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
f0f0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
f100: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
f110: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
f120: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
f130: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
f140: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
f150: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
f160: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
f170: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
f180: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
f190: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
f1a0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f1b0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
f1c0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
f1d0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
f1e0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
f1f0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
f200: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
f210: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
f220: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
f230: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
f240: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
f250: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f260: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
f270: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
f280: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
f290: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
f2a0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
f2b0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
f2c0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
f2d0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
f2e0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f2f0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
f300: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
f310: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
f320: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
f330: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
f340: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
f350: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f360: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
f370: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
f380: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
f390: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
f3a0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
f3b0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
f3c0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
f3d0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
f3e0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
f3f0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
f400: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
f410: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
f420: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
f430: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
f440: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
f450: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
f460: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
f470: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
f480: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
f490: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
f4a0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
f4b0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
f4c0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
f4d0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
f4e0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
f4f0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
f500: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
f510: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
f520: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
f530: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
f540: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
f550: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
f560: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
f570: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
f580: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
f590: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
f5a0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
f5b0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
f5c0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
f5d0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
f5e0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
f5f0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
f600: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
f610: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
f620: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
f630: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
f640: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
f650: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
f660: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
f670: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
f680: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
f690: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
f6a0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
f6b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
f6c0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
f6d0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
f6e0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
f6f0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
f700: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
f710: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
f720: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
f730: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
f740: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
f750: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
f760: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
f770: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
f780: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
f790: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
f7a0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
f7b0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
f7c0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
f7d0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
f7e0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
f7f0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
f800: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
f810: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
f820: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
f830: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
f840: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
f850: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
f860: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
f870: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f880: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
f890: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
f8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
f8b0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
f8c0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
f8d0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
f8e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f8f0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
f900: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
f910: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
f920: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f930: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
f940: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
f950: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
f960: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
f970: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f980: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f990: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
f9a0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
f9b0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
f9c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
f9d0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
f9e0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
f9f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
fa00: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
fa10: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
fa20: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
fa30: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
fa40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
fa50: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
fa60: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
fa70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
fa80: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
fa90: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
faa0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
fab0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
fac0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
fad0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fae0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
faf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
fb00: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
fb10: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
fb20: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
fb30: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
fb40: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
fb50: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
fb60: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
fb70: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
fb80: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
fb90: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
fba0: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
fbb0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
fbc0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
fbd0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
fbe0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
fbf0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
fc00: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
fc10: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
fc20: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
fc30: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
fc40: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
fc50: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
fc60: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
fc70: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
fc80: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
fc90: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
fca0: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
fcb0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
fcc0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fcd0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
fce0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
fcf0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
fd00: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
fd10: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
fd20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
fd30: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
fd40: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
fd50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fd60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fd70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
fd80: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
fd90: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
fda0: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
fdb0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
fdc0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fdd0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
fde0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
fdf0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
fe00: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
fe10: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
fe20: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
fe30: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
fe40: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
fe50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
fe60: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
fe70: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
fe80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
fe90: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
fea0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
feb0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
fec0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
fed0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
fee0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
fef0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
ff00: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
ff10: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
ff20: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
ff30: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
ff40: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
ff50: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ff60: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ff70: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ff80: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ff90: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ffa0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ffb0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ffc0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ffd0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ffe0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
fff0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
10000 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
10010 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
10020 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
10030 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
10040 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
10050 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
10060 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
10070 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
10080 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
10090 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
100a0 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
100b0 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
100c0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
100d0 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
100e0 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
100f0 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
10100 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10110 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10120 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
10130 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
10140 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
10150 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
10160 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
10170 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
10180 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
10190 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
101a0 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
101b0 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
101c0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
101d0 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
101e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
101f0 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
10200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10210 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
10220 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
10230 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
10240 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
10250 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10260 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
10270 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
10280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10290 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
102a0 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
102b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
102c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
102d0 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
102e0 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
102f0 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
10300 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
10310 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
10320 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
10330 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
10340 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
10350 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
10360 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
10370 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
10380 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
10390 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
103a0 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
103b0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
103c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
103d0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
103e0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
103f0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
10400 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
10410 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
10420 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
10430 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
10440 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
10450 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
10460 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
10470 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
10480 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
10490 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
104a0 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
104b0 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
104c0 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
104d0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
104e0 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
104f0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
10500 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
10510 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
10520 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
10530 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
10540 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
10550 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
10560 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
10570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10580 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
10590 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
105a0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
105b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
105c0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
105d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
105e0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
105f0 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
10610 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
10620 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
10630 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
10640 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10650 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
10660 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
10670 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
10680 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
10690 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
106a0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
106b0 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
106c0 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
106d0 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
106e0 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
106f0 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
10700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10710 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
10720 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
10730 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
10740 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10760 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10770 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
10780 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
10790 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
107a0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
107b0 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
107c0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
107d0 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
107e0 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
107f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10800 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
10810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
10820 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
10830 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
10840 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
10850 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
10860 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
10870 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
10880 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
10890 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
108a0 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
108b0 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
108c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
108d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
108e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108f0 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
10900 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
10910 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
10920 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10930 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
10940 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
10950 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
10960 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
10970 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10980 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10990 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
109a0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
109b0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
109c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
109d0 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
109e0 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
109f0 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
10a00 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
10a10 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
10a20 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
10a30 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
10a40 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
10a50 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
10a60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
10a70 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
10a80 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
10a90 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
10aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10ab0 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
10ac0 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
10ad0 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
10ae0 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
10af0 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
10b00 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
10b10 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
10b20 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
10b30 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
10b40 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
10b50 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
10b60 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
10b70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10b80 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10b90 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
10ba0 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
10bb0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
10bc0 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
10bd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10be0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
10bf0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
10c00 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
10c10 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
10c20 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
10c30 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
10c40 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
10c50 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
10c60 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
10c70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
10c80 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
10c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
10ca0 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
10cb0 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
10cc0 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
10cd0 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
10ce0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
10cf0 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
10d00 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
10d10 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
10d20 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
10d30 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
10d40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10d50 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10d60 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
10d70 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10d80 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
10d90 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
10da0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10db0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
10dc0 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
10dd0 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
10de0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10df0 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
10e00 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
10e10 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
10e20 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
10e30 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
10e40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
10e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
10e60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10e70 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
10e80 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
10e90 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
10ea0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10eb0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
10ec0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
10ed0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
10ee0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
10ef0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f00 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
10f10 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
10f20 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
10f30 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
10f40 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
10f50 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10f60 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
10f70 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
10f80 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
10f90 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
10fa0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
10fb0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
10fc0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
10fd0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
10fe0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10ff0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
11000 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
11010 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11020 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
11030 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
11040 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11050 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
11060 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
11070 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
11080 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
11090 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
110a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
110b0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
110c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
110d0 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
110e0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
110f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
11100 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
11110 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
11120 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11130 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
11140 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
11150 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11160 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
11170 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
11180 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
11190 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
111a0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
111b0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
111c0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
111d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
111e0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
111f0 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
11200 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
11210 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
11220 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
11230 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
11240 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11250 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
11260 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
11270 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
11280 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
11290 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
112a0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
112b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
112c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
112d0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
112e0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
112f0 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
11300 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
11310 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
11320 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
11330 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
11340 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
11350 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
11360 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
11370 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
11380 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
11390 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
113a0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
113b0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
113c0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
113d0 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
113e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
113f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
11400 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
11410 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
11420 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
11430 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
11440 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
11450 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
11460 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
11470 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
11480 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11490 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
114a0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
114b0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
114c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
114d0 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
114e0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
114f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
11500 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
11510 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
11520 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
11530 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
11540 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
11550 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
11560 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11570 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11580 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
11590 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
115a0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
115b0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
115c0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
115d0 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
115e0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
115f0 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
11600 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
11610 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
11620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
11630 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
11640 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
11650 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
11660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11670 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
11680 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11690 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
116a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
116b0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
116c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
116d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
116e0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
116f0 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
11700 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
11710 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
11720 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
11730 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
11740 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
11750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11760 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
11770 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
11780 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
11790 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
117a0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
117b0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
117c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
117d0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
117e0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
117f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11800 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11810 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
11820 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
11830 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
11840 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
11850 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
11860 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
11870 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
11880 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
11890 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
118a0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
118b0 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
118c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
118d0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
118e0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
118f0 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
11900 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
11910 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
11920 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
11930 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
11940 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
11950 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11960 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
11970 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
11980 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
11990 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
119a0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
119b0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
119c0 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
119d0 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
119e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
119f0 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
11a00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
11a10 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
11a20 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
11a30 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
11a40 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
11a50 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
11a60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
11a70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
11a80 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
11a90 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
11aa0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
11ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11ac0 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
11ad0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11ae0 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
11af0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
11b00 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
11b10 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
11b20 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
11b30 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
11b40 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
11b50 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
11b60 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
11b70 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
11b80 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
11b90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
11ba0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
11bb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
11bc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11be0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
11bf0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
11c00 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
11c10 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
11c20 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
11c30 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
11c40 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
11c50 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
11c60 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
11c70 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
11c80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
11c90 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
11ca0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
11cb0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
11cc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11cd0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
11ce0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
11cf0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
11d00 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
11d10 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
11d20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
11d30 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
11d40 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
11d50 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
11d60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
11d70 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
11d80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
11d90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
11da0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
11db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11dc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
11dd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
11de0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
11df0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11e00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
11e20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
11e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11e40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
11e50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
11e60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11e70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
11e80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
11e90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
11ea0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11ec0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11ed0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11ee0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11ef0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11f00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11f10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11f20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11f30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
11f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11f50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
11f60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
11f70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
11f80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
11f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11fa0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
11fb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11fc0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11fd0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11fe0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11ff0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
12000 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
12010 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
12020 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
12030 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
12040 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
12050 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
12060 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12070 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
12080 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
12090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
120a0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
120b0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
120c0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
120d0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
120e0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
120f0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
12100 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
12110 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12120 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
12130 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
12140 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
12150 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
12160 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
12170 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
12180 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12190 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
121a0 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
121b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
121c0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
121d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
121e0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
121f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12200 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
12210 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12220 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
12230 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
12240 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
12250 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
12260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
12270 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
12280 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
12290 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
122a0 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
122b0 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
122c0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
122d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
122e0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
122f0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
12300 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
12310 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
12320 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
12330 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
12340 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
12350 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
12370 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
12380 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
12390 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
123a0 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
123b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
123c0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
123d0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
123e0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
123f0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
12400 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
12410 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
12420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
12430 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
12440 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
12450 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
12460 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
12470 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
12480 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12490 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
124a0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
124b0 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
124c0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
124d0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
124e0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
124f0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
12500 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
12510 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
12520 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
12530 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
12540 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
12550 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
12560 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
12570 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
12580 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
12590 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
125a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
125b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
125c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
125d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
125e0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
125f0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
12600 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
12610 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
12620 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
12630 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
12640 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
12650 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
12660 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
12670 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
12680 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
12690 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
126a0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
126b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
126c0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
126d0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
126e0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
126f0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
12700 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
12710 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
12720 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
12730 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
12740 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12750 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
12760 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
12770 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
12780 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
12790 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
127a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
127b0 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
127c0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
127d0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
127e0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
127f0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
12800 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
12810 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
12820 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12830 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
12840 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
12850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
12860 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
12870 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
12880 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
12890 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
128a0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
128b0 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
128c0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
128d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
128e0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
128f0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
12900 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
12910 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
12920 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
12930 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
12940 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
12950 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
12960 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
12970 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
12980 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
12990 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
129a0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
129c0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
129d0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
129e0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
129f0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
12a00 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
12a10 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
12a20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
12a30 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
12a40 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
12a50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
12a60 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
12a70 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
12a80 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
12a90 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
12aa0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
12ab0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
12ac0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
12ad0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
12ae0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
12af0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
12b00 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
12b10 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
12b20 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
12b30 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
12b40 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
12b50 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
12b60 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
12b70 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
12b80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12b90 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
12ba0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
12bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12bc0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
12bd0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
12be0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
12bf0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
12c00 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
12c10 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
12c20 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
12c30 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
12c40 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
12c50 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
12c60 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
12c70 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
12c80 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
12c90 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
12ca0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
12cb0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
12cc0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
12cd0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
12ce0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
12cf0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
12d00 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
12d10 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
12d20 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
12d30 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
12d40 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
12d50 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
12d60 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12d70 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
12d80 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
12d90 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
12da0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
12db0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
12dc0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
12dd0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
12de0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12df0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
12e00 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
12e10 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
12e20 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
12e30 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
12e40 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
12e50 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
12e60 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12e70 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
12e80 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
12e90 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
12ea0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
12eb0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
12ec0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
12ed0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12ee0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
12ef0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
12f00 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
12f10 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
12f20 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
12f30 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
12f40 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
12f50 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
12f60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12f70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
12f80 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
12f90 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
12fa0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
12fb0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
12fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12fd0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
12fe0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
12ff0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
13000 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
13010 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
13020 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
13030 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
13040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13050 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
13060 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
13070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13080 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
13090 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
130a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
130b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
130c0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
130d0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
130e0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
130f0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
13100 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13110 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
13120 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
13130 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
13140 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
13150 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
13160 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
13170 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
13180 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
13190 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
131a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
131b0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
131c0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
131d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
131e0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
131f0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
13200 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13210 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
13220 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
13230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13240 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
13250 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13260 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
13270 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
13280 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
13290 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
132a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
132b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
132c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
132d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
132e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
132f0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
13300 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
13310 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
13320 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
13330 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
13340 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
13350 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
13360 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13370 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13380 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13390 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
133a0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
133b0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
133c0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
133d0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
133e0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
133f0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
13400 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
13410 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
13420 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
13430 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13440 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
13450 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13460 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
13470 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13480 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
13490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
134a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
134b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
134c0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
134d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
134e0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
134f0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13510 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
13520 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13530 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
13540 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
13550 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
13560 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
13570 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
13580 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
13590 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
135a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
135b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
135c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
135d0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
135e0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
135f0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
13600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13610 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13620 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
13630 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
13640 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
13650 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13660 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
13670 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
13680 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
13690 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
136a0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
136b0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
136c0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
136d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
136e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
136f0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13700 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13710 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13720 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13730 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13740 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13750 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13760 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
13770 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
13780 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
13790 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
137a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
137b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
137c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
137d0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
137e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
137f0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
13800 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
13830 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
13840 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13850 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
13860 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13870 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13880 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13890 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
138a0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
138b0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
138c0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
138d0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
138e0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
138f0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
13900 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
13910 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
13920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13930 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13940 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
13950 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
13960 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
13970 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
13980 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13990 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
139a0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
139b0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
139c0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
139d0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
139e0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
139f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
13a00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13a10 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
13a20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
13a30 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
13a40 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
13a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13a60 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
13a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13a80 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
13a90 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
13aa0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
13ab0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13ac0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13ae0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13af0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13b00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13b10 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13b20 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
13b30 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
13b40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13b50 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
13b60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13b70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13b80 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13b90 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
13ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13bb0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
13bc0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13bd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13be0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
13bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13c00 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
13c10 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13c30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13c40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13c50 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
13c60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13c70 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13c80 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13c90 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
13ca0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
13cb0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
13cc0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13ce0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
13cf0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
13d00 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
13d10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13d20 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13d30 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
13d40 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
13d50 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
13d60 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
13d70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13d80 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13d90 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
13da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
13db0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13dc0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13de0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
13df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13e00 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
13e10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13e20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13e30 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13e50 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
13e60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13e80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13e90 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13ea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
13eb0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
13ec0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13ed0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13ee0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
13ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13f00 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13f10 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13f20 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13f30 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13f40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f50 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13f60 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
13f70 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
13f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13f90 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
13fa0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
13fb0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
13fc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
13fe0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14000 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  L_MALLOC</dt>.**
14010 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14020 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
14030 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14040 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
14050 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e  nt of.** type in
14060 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
14070 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
14080 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 69  ch if true provi
14090 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a  des a hint to.**
140a0 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
140b0 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72  should avoid lar
140c0 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ge memory alloca
140d0 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c  tions if possibl
140e0 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  e..** SQLite wil
140f0 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 20  l run faster if 
14100 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61  it is free to ma
14110 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  ke large memory 
14120 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20  allocations,.** 
14130 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61  but some applica
14140 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65  tion might prefe
14150 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20  r to run slower 
14160 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a  in exchange for.
14170 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 62  ** guarantees ab
14180 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d  out memory fragm
14190 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72  entation that ar
141a0 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61  e possible if la
141b0 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  rge.** allocatio
141c0 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20  ns are avoided. 
141d0 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
141e0 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c  rmally off..** <
141f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14200 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14210 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
14220 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14230 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
14240 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14250 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
14260 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
14270 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14280 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
14290 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
142a0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
142b0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
142c0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
142d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
142e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
142f0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
14300 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14310 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
14320 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
14330 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
14340 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
14350 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
14360 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
14370 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
14380 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
14390 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
143a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
143b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
143c0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
143d0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
143e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
143f0 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
14400 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
14410 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14420 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
14430 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
14440 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
14450 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
14460 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
14470 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
14480 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
14490 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
144a0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
144b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
144c0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
144d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
144e0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
144f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14500 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
14510 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14520 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
14530 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
14540 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   used..** </dd>.
14550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14560 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14570 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14580 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
14590 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
145a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
145b0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
145c0 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72  pecifies a memor
145d0 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53  y pool.** that S
145e0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
145f0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  r the database p
14600 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
14610 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a  he default page.
14620 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
14630 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
14640 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
14650 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d   option is a no-
14660 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  op if an applica
14670 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
14680 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
14690 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
146a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
146b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
146c0 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  HE2]..** ^There 
146d0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
146e0 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
146f0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
14700 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
14710 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
14720 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68  emory (pMem), th
14730 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
14740 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28  age cache line (
14750 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
14760 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20  number of cache 
14770 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  lines (N)..** Th
14780 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
14790 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
147a0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
147b0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
147c0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
147d0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
147e0 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
147f0 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
14800 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
14810 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
14820 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
14830 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
14840 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
14850 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
14860 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  d using [SQLITE_
14870 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
14880 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  RSZ]..** ^It is 
14890 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
148a0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
148b0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
148c0 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
148d0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
148e0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
148f0 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65  e pMem.** argume
14900 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  nt must be eithe
14910 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
14920 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
14930 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14940 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
14950 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
14960 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74  t sz*N bytes, ot
14970 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65  herwise.** subse
14980 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
14990 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
149a0 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f  ^When pMem is no
149b0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
149c0 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73  ill strive to us
149d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
149e0 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69  vided.** to sati
149f0 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e  sfy page cache n
14a00 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61  eeds, falling ba
14a10 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ck to [sqlite3_m
14a20 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61  alloc()] if.** a
14a30 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14a40 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20   is larger than 
14a50 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61  sz bytes or if a
14a60 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62  ll of the pMem b
14a70 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61  uffer.** is exha
14a80 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d  usted..** ^If pM
14a90 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  em is NULL and N
14aa0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
14ab0 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  en each database
14ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64   connection.** d
14ad0 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62  oes an initial b
14ae0 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ulk allocation f
14af0 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
14b00 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  mory.** from [sq
14b10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14b20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e  sufficient for N
14b30 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20   cache lines if 
14b40 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72  N is positive or
14b50 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62  .** of -1024*N b
14b60 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67  ytes if N is neg
14b70 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64  ative, . ^If add
14b80 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
14b90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
14ba0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
14bb0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14bc0 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a  y the initial.**
14bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
14be0 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  n SQLite goes to
14bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14c00 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66  ()] separately f
14c10 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74  or each.** addit
14c20 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65  ional cache line
14c30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14c50 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
14c60 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
14c70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14c90 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14ca0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14cb0 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
14cc0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
14cd0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
14ce0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14d00 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
14d10 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
14d20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14d30 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
14d40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14d50 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
14d60 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14d70 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
14d80 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
14d90 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
14da0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
14db0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14dc0 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
14dd0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
14de0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
14df0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
14e00 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14e10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
14e30 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
14e40 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
14e50 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
14e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
14e70 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
14e80 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
14e90 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14ea0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
14eb0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
14ec0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14ed0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
14ee0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
14ef0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
14f00 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
14f10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
14f20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
14f30 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
14f40 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
14f50 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
14f60 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
14f80 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
14f90 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
14fa0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
14fb0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
14fc0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
14fd0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
14fe0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
14ff0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
15000 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
15010 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
15020 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
15030 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
15040 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15050 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
15060 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
15070 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
15080 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
15090 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
150a0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
150b0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
150c0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
150d0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
150e0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
150f0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
15100 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
15110 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
15120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15130 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
15140 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
15150 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15170 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15190 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
151a0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
151b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
151c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
151d0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
151e0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
151f0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
15200 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
15210 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
15220 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
15230 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
15240 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
15250 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
15260 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
15270 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
15280 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
15290 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
152a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
152b0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
152c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
152d0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
152e0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
152f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15300 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15310 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15320 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15330 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15340 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
15350 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
15360 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
15370 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
15380 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
15390 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
153a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
153b0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
153c0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
153d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
153e0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
153f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
15400 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15410 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15420 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15430 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
15440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15450 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15460 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
15470 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15480 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
15490 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
154a0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
154b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
154c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
154d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
154e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
154f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15500 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15510 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
15520 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
15530 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
15540 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
15550 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
15560 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
15570 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
15580 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
15590 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
155a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
155b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
155c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
155d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
155e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
155f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15600 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15610 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15620 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15630 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15640 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15650 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
15660 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
15670 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
15680 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
15690 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
156a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
156b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
156d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
156e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
156f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15700 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
15710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
15730 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15740 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
15750 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15760 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15770 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
15780 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15790 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
157a0 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
157b0 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
157c0 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
157d0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
157e0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
157f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15800 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15810 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15820 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
15830 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
15840 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15850 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
15860 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
15870 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
15880 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
15890 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
158a0 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
158b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
158c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
158d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
158e0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
158f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
15900 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
15910 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
15920 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
15930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
15940 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
15950 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
15960 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15970 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
15980 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15990 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
159a0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
159b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
159c0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
159d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
159e0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
159f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
15a00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15a10 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15a20 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
15a30 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
15a40 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
15a50 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
15a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
15a70 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
15a80 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
15a90 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15aa0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15ab0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
15ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15ad0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
15ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15af0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
15b00 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15b10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15b20 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
15b30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15b40 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
15b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
15b60 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15b70 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15b80 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15b90 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
15ba0 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
15bb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15bc0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15bf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15c00 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15c10 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
15c20 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
15c30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
15c40 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
15c50 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
15c60 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
15c70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c80 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
15c90 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
15ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
15cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
15cc0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
15cd0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
15ce0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
15cf0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
15d00 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
15d10 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
15d20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
15d30 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
15d40 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
15d50 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
15d60 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
15d70 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
15d80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
15d90 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
15da0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
15db0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
15dc0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
15dd0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
15de0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
15df0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15e10 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
15e20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
15e30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15e40 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
15e50 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
15e60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
15e70 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
15e80 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
15e90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
15ea0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
15eb0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15ec0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15ed0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15ee0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
15ef0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
15f00 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
15f10 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
15f20 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
15f30 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
15f40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
15f50 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
15f60 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
15f70 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
15f80 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
15f90 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
15fa0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
15fb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
15fc0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
15fd0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
15fe0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16000 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
16010 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
16020 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
16030 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
16040 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
16050 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
16060 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
16070 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16080 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
16090 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
160a0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
160b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
160d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
160e0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
160f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16100 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
16110 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16120 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
16130 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
16140 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
16150 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
16160 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
16170 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
16180 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
16190 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
161a0 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
161b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
161c0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
161d0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
161e0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
161f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
16200 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16210 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
16220 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
16230 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
16240 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
16250 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
16260 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
16270 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16280 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
162a0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
162b0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
162c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
162d0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
162e0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
162f0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
16300 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
16310 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16320 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
16330 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
16340 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16350 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16360 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16370 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
16380 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16390 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
163a0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
163b0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
163c0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
163d0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
163e0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
163f0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
16400 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
16410 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16420 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
16430 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16440 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16450 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
16460 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16470 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16480 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
16490 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
164a0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
164b0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
164c0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
164d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
164e0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
164f0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
16500 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
16510 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
16520 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
16530 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
16540 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16550 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
16560 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
16570 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
16580 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
16590 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
165a0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
165b0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
165c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
165d0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
165e0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
165f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
16600 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
16610 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
16620 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
16630 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
16640 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
16650 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
16660 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
16670 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
16680 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
16690 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
166a0 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
166b0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
166c0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
166d0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
166e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
166f0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
16700 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
16710 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
16720 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
16730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16740 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
16750 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
16760 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
16770 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16780 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
167a0 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
167b0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
167c0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
167d0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
167e0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
167f0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
16800 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
16810 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
16820 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
16830 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
16840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
16850 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
16860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16870 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
16880 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
16890 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
168a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
168b0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
168c0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
168d0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
168e0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
168f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16900 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
16910 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
16920 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
16930 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
16940 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
16950 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
16960 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
16970 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
16980 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
16990 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
169a0 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
169b0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
169c0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
169d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
169e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
169f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16a00 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
16a10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16a20 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
16a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a40 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
16a50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16a60 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
16a70 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
16a80 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
16a90 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
16aa0 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
16ab0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
16ac0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
16ad0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
16ae0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
16af0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
16b00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
16b10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16b20 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
16b30 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
16b40 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
16b50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
16b60 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
16b70 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
16b80 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
16b90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16ba0 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
16bb0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
16bc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
16bd0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
16be0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
16bf0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
16c00 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
16c10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
16c20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
16c30 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
16c40 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
16c50 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
16c60 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
16c70 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
16c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16c90 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
16ca0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16cb0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
16cc0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
16cd0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
16ce0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
16cf0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
16d00 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
16d10 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
16d20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
16d30 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
16d40 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
16d50 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
16d60 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
16d70 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
16d80 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
16d90 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16da0 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
16db0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
16dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16dd0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
16de0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
16df0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
16e00 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
16e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
16e20 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
16e30 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
16e40 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16e50 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
16e60 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
16e70 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
16e80 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
16e90 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
16ea0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
16eb0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
16ec0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
16ed0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
16ee0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
16ef0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16f00 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
16f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
16f20 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
16f30 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
16f40 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
16f50 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
16f60 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
16f70 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
16f80 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16f90 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
16fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16fb0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
16fc0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16fd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16fe0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
16ff0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
17000 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
17010 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
17020 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
17030 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
17040 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
17050 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
17060 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
17070 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17080 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
17090 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
170a0 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
170b0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
170c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
170d0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
170e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
170f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17100 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
17110 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17120 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
17130 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17140 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
17150 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17160 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17170 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
17180 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17190 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
171a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
171b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
171c0 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
171d0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
171e0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
171f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17200 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
17210 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
17220 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
17230 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
17240 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
17250 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
17260 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
17270 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
17280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17290 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
172b0 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
172c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
172d0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
172e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
172f0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
17300 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
17310 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
17320 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
17330 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
17340 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
17350 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
17360 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
17370 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
17380 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
17390 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
173a0 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
173b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
173c0 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
173d0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
173e0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
173f0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
17400 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
17410 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
17420 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
17430 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
17440 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
17450 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
17460 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
17470 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
17480 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
17490 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
174a0 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
174b0 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
174c0 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
174d0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
174e0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
174f0 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74  L_SPILL]].** <dt
17500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
17510 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a  TMTJRNL_SPILL.**
17520 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17530 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17540 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61  _SPILL option ta
17550 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17560 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17570 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61  becomes the [sta
17580 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20  tement journal] 
17590 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68  spill-to-disk th
175a0 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53  reshold.  .** [S
175b0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
175c0 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  s] are held in m
175d0 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69  emory until thei
175e0 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73  r size (in bytes
175f0 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69  ).** exceeds thi
17600 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20  s threshold, at 
17610 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79  which point they
17620 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20   are written to 
17630 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74  disk..** Or if t
17640 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20  he threshold is 
17650 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  -1, statement jo
17660 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79  urnals are alway
17670 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73  s held.** exclus
17680 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e  ively in memory.
17690 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73  .** Since many s
176a0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
176b0 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c  s never become l
176c0 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68  arge, setting th
176d0 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73  e spill.** thres
176e0 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20  hold to a value 
176f0 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61  such as 64KiB ca
17700 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65  n greatly reduce
17710 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a   the amount of.*
17720 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74  * I/O required t
17730 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d  o support statem
17740 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  ent rollback..**
17750 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
17760 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74  ue for this sett
17770 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65  ing is controlle
17780 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  d by the.** [SQL
17790 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  ITE_STMTJRNL_SPI
177a0 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  LL] compile-time
177b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c   option..** </dl
177c0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
177d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
177e0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
177f0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
17810 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
17820 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
17830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
17840 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
17850 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
17870 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
17880 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
17890 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
178d0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178f0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
17900 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  6  /* No longer 
17910 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
17920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17930 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
17940 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
17950 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
17960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17970 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
17980 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
17990 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
179c0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
179d0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
179e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
179f0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
17a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
17a10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
17a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17a30 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
17a40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
17a50 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
17a60 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
17a70 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
17a80 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
17a90 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
17aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ab0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17ac0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
17ad0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17af0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
17b00 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17b20 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
17b30 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17b40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17b50 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
17b60 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
17b70 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
17b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
17b90 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
17ba0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17bc0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
17bd0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17be0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17c00 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
17c10 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
17c20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c40 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
17c50 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
17c60 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
17c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17c80 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
17c90 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
17ca0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
17cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17cc0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
17cd0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
17ce0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
17cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d00 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17d10 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
17d20 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
17d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17d40 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17d50 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
17d60 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
17d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17d80 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
17d90 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
17da0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
17db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17dc0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17dd0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
17de0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e00 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
17e10 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f  LOC        27  /
17e20 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a  * boolean */../*
17e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
17e40 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
17e50 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
17e60 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17e70 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17e80 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17e90 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17eb0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17ec0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17ed0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17ee0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17ef0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17f00 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
17f10 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17f20 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
17f30 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
17f40 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
17f50 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
17f60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17f70 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17f80 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17f90 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17fa0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17fb0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17fc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17fd0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17fe0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17ff0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
18000 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18010 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
18020 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
18030 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
18040 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
18050 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
18060 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
18070 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
18080 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
18090 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
180a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
180b0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
180c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
180d0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
180e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
180f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
18100 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
18110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18120 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
18130 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
18140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
18150 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18160 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
18170 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
18180 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18190 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
181a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
181b0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
181c0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
181d0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
181e0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
181f0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18210 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18220 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
18230 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
18240 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
18250 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
18260 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
18270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
18280 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18290 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
182a0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
182b0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
182c0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
182d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
182e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
182f0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18300 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18320 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
18330 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
18340 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
18350 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
18360 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
18370 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
18380 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18390 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
183a0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
183b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
183c0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
183d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
183e0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
183f0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18400 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18410 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
18420 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
18430 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
18440 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
18450 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
18460 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
18470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18480 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
18490 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
184a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
184b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
184c0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
184d0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
184e0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
184f0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18500 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
18520 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
18530 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18540 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
18550 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
18560 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
18570 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18580 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
18590 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
185a0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
185b0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
185c0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
185d0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
185e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
185f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18600 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18610 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
18620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18630 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18640 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18650 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
18660 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
18670 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
18680 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
18690 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
186a0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
186b0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
186c0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
186d0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
186e0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
186f0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18700 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18710 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18720 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
18730 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
18740 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
18750 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
18760 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18770 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18780 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18790 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
187a0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
187b0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
187c0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
187d0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
187e0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
187f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18800 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18810 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18820 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
18830 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
18840 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18850 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18860 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18870 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18880 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
18890 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
188a0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
188b0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
188c0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
188d0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
188e0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
188f0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18900 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18920 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18930 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18940 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
18950 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18960 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
18970 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18980 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
18990 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
189a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
189b0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
189c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
189d0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
189e0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189f0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18a00 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18a10 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18a20 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18a30 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18a40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18a50 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18a60 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18a70 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
18a80 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
18a90 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18aa0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18ab0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18ac0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18ad0 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
18ae0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18af0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18b00 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18b10 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
18b20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
18b30 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
18b40 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
18b50 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
18b60 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
18b70 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
18b80 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
18b90 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18ba0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18bb0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18bc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18bd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18be0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18bf0 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
18c00 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
18c10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18c20 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18c30 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
18c40 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
18c50 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
18c60 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18c70 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18c80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18c90 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18ca0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18cb0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18cc0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18cd0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18ce0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18cf0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18d00 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
18d10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18d20 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18d30 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18d40 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
18d50 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18d60 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18d70 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18d80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18d90 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18db0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18dc0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18dd0 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18de0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18df0 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18e00 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
18e10 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18e20 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
18e30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18e40 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
18e50 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18e60 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18e70 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18e80 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18e90 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18ea0 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18ec0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18ed0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18ee0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18ef0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18f00 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
18f10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18f20 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
18f30 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
18f40 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
18f50 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
18f60 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18f70 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18f80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18f90 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18fa0 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18fb0 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18fc0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18fd0 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18fe0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
19000 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
19010 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
19020 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
19030 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
19040 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
19050 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19060 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19070 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19080 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19090 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
190a0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
190b0 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
190c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
190d0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
190e0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
190f0 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
19100 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19110 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19120 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
19130 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
19140 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
19150 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
19160 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
19170 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19180 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19190 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
191a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
191b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
191c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
191d0 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
191e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
191f0 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19210 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
19220 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
19230 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
19240 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
19250 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
19260 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
19270 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
19280 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
19290 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
192a0 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
192b0 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
192c0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
192d0 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
192e0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
192f0 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19300 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19310 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
19320 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
19330 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
19340 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
19350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19360 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
19370 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
19380 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
19390 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
193a0 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
193b0 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
193c0 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
193d0 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
193e0 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
193f0 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19400 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19410 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
19420 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
19430 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
19440 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
19450 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
19460 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
19470 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
19480 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
19490 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
194a0 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
194b0 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
194c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
194d0 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
194e0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
194f0 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73  an integer - pos
19500 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65  itive to disable
19510 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19520 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
19530 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
19540 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20  to enable them, 
19550 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20  and negative to 
19560 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
19570 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
19580 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19590 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
195a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
195b0 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
195c0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
195d0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
195e0 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
195f0 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
19600 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19610 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
19620 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19630 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19640 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19650 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19660 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
19670 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
19680 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19690 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
196a0 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
196b0 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
196c0 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
196d0 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
196e0 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
196f0 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
19700 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
19710 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
19720 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
19730 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
19740 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
19750 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
19760 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
19770 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
19780 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
19790 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
197a0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
197b0 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
197c0 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
197d0 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
197e0 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
197f0 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
19800 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
19810 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
19820 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
19830 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
19840 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
19850 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
19860 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
19870 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
19880 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
19890 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
198a0 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
198b0 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72   lab..** The fir
198c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
198d0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
198e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
198f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19900 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f  .** the QPSG, po
19910 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19920 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69   QPSG, or negati
19930 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19940 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
19950 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64  nged. The second
19960 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19970 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19980 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19990 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
199a0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
199b0 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50  e whether the QP
199c0 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  SG is disabled o
199d0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
199e0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
199f0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19a00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19a10 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
19a20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79  </dt>.** <dd> By
19a30 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75   default, the ou
19a40 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20  tput of EXPLAIN 
19a50 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61  QUERY PLAN comma
19a60 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a  nds does not .**
19a70 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20   include output 
19a80 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f  for any operatio
19a90 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ns performed by 
19aa0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
19ab0 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e  . This.** option
19ac0 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
19ad0 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65  or clear (the de
19ae0 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68  fault) a flag th
19af0 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a  at governs this.
19b00 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65  ** behavior. The
19b10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19b20 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19b30 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
19b40 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73  integer -.** pos
19b50 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
19b60 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67  output for trigg
19b70 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20  er programs, or 
19b80 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
19b90 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69  it,.** or negati
19ba0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19bb0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19bc0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19bd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19be0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19bf0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19c00 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20   is written .** 
19c10 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19c20 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75  te whether outpu
19c30 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68  t-for-triggers h
19c40 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  as been disabled
19c50 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69   - 0 if .** it i
19c60 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  s not disabled, 
19c70 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a  1 if it is.  .**
19c80 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   </dd>.** </dl>.
19c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19ca0 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
19cb0 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
19cc0 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
19cd0 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
19ce0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19cf0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
19d00 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
19d10 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
19d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19d30 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
19d40 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
19d50 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
19d60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19d70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19d80 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
19d90 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
19da0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19db0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19dc0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19dd0 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
19de0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19df0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19e00 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
19e10 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
19e20 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
19e30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
19e40 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20  O_CKPT_ON_CLOSE 
19e50 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74       1006 /* int
19e60 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19e70 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19e80 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20  _ENABLE_QPSG    
19e90 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69         1007 /* i
19ea0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19eb0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19ec0 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20  IG_TRIGGER_EQP  
19ed0 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a           1008 /*
19ee0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19f00 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20  NFIG_MAX        
19f10 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
19f20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e  /* Largest DBCON
19f30 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  FIG */../*.** CA
19f40 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
19f50 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
19f60 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
19f70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19f80 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
19f90 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
19fa0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
19fb0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
19fc0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
19fd0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
19fe0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
19ff0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
1a000 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1a010 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
1a020 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1a030 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
1a040 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a050 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1a060 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1a070 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
1a080 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
1a090 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
1a0a0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
1a0b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a0c0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
1a0d0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
1a0e0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
1a0f0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
1a100 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
1a110 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
1a120 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
1a130 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
1a140 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
1a150 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
1a160 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
1a170 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
1a180 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
1a190 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
1a1a0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
1a1b0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
1a1c0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
1a1d0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
1a1e0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1a1f0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
1a200 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
1a210 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
1a220 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
1a230 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
1a240 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
1a250 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
1a260 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
1a270 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
1a280 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a290 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75  D) interface usu
1a2a0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1a2b0 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74   [rowid] of.** t
1a2c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
1a2d0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1a2e0 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
1a2f0 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
1a300 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
1a310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a320 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69  on D. ^Inserts i
1a330 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
1a340 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
1a350 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20  ot.** recorded. 
1a360 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1a370 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
1a380 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61   rowid tables ha
1a390 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
1a3a0 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61   .** on the data
1a3b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a3c0 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  D, then sqlite3_
1a3d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a3e0 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a  d(D) returns .**
1a3f0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   zero..**.** As 
1a400 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65  well as being se
1a410 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  t automatically 
1a420 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65  as rows are inse
1a430 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61  rted into databa
1a440 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68  se.** tables, th
1a450 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a460 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1a470 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70  n may be set exp
1a480 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73  licitly by.** [s
1a490 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1a4a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1a4b0 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75  **.** Some virtu
1a4c0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1a4d0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53  ntations may INS
1a4e0 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f  ERT rows into ro
1a4f0 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a  wid tables as.**
1a500 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74   part of committ
1a510 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
1a520 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68  n (e.g. to flush
1a530 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65   data accumulate
1a540 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74  d in memory.** t
1a550 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73  o disk). In this
1a560 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74   case subsequent
1a570 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66   calls to this f
1a580 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74  unction return t
1a590 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f  he rowid.** asso
1a5a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73  ciated with thes
1a5b0 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52  e internal INSER
1a5c0 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68  T operations, wh
1a5d0 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a  ich leads to .**
1a5e0 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73   unintuitive res
1a5f0 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61  ults. Virtual ta
1a600 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
1a610 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74  ons that do writ
1a620 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61  e to rowid.** ta
1a630 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79  bles in this way
1a640 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20   can avoid this 
1a650 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f  problem by resto
1a660 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
1a670 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75  l .** rowid valu
1a680 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1a690 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1a6a0 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65  _rowid()] before
1a6b0 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63   returning .** c
1a6c0 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73  ontrol to the us
1a6d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  er..**.** ^(If a
1a6e0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
1a6f0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
1a700 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  er then this rou
1a710 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65  tine will .** re
1a720 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1a730 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1a740 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
1a750 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a  the trigger is .
1a760 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65  ** running. Once
1a770 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1a780 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76  gram ends, the v
1a790 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
1a7a0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
1a7b0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
1a7c0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
1a7d0 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20  the trigger was 
1a7e0 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  fired.)^.**.** ^
1a7f0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
1a800 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
1a810 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1a820 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
1a830 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1a840 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
1a850 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
1a860 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
1a870 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
1a880 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
1a890 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
1a8a0 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
1a8b0 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
1a8c0 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
1a8d0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
1a8e0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
1a8f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
1a900 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
1a910 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
1a920 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
1a930 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1a940 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
1a950 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1a960 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
1a970 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
1a980 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
1a990 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
1a9a0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
1a9b0 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
1a9c0 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
1a9d0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
1a9e0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
1a9f0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
1aa00 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
1aa10 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
1aa20 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
1aa30 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
1aa40 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
1aa50 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
1aa60 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
1aa70 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
1aa80 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
1aa90 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
1aaa0 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
1aab0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
1aac0 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
1aad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
1aae0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
1aaf0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
1ab00 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1ab10 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1ab20 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
1ab30 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
1ab40 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
1ab50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab60 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
1ab70 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1ab80 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
1ab90 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1aba0 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
1abb0 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
1abc0 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
1abd0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1abe0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1abf0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1ac00 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
1ac10 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1ac20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
1ac30 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
1ac40 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
1ac50 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1ac60 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1ac70 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
1ac80 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1ac90 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1aca0 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65  API3REF: Set the
1acb0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1acc0 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54  id value..** MET
1acd0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1ace0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
1acf0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1ad00 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f  owid(D, R) metho
1ad10 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70  d allows the app
1ad20 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73  lication to.** s
1ad30 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  et the value ret
1ad40 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  urned by calling
1ad50 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1ad60 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f  sert_rowid(D) to
1ad70 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69   R .** without i
1ad80 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69  nserting a row i
1ad90 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
1ada0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1adb0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1adc0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1add0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
1ade0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1adf0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
1ae00 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1ae10 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1ae20 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1ae30 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1ae40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1ae50 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
1ae60 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
1ae70 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
1ae80 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
1ae90 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
1aea0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
1aeb0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
1aec0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1aed0 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
1aee0 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
1aef0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
1af00 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1af10 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1af20 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
1af30 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
1af40 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1af50 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
1af60 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
1af70 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
1af80 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
1af90 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1afa0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
1afb0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
1afc0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1afd0 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
1afe0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1aff0 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
1b000 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1b010 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
1b020 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1b030 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
1b040 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
1b050 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1b060 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1b070 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
1b080 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
1b090 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1b0a0 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
1b0b0 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
1b0c0 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
1b0d0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1b0e0 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
1b0f0 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
1b100 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
1b110 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b120 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
1b130 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
1b140 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1b150 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
1b160 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
1b170 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
1b180 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
1b190 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
1b1a0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1b1b0 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
1b1c0 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
1b1d0 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
1b1e0 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
1b1f0 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
1b200 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
1b210 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1b220 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
1b230 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
1b240 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1b250 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
1b260 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
1b270 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
1b280 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
1b290 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
1b2a0 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
1b2b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
1b2c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b2d0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
1b2e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1b2f0 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
1b300 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
1b310 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
1b320 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
1b330 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
1b340 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
1b350 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
1b360 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
1b370 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1b380 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
1b390 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
1b3a0 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
1b3b0 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
1b3c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1b3d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b3e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
1b3f0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
1b400 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
1b410 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
1b420 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
1b430 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
1b440 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
1b450 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
1b460 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
1b470 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1b480 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
1b490 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
1b4a0 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
1b4b0 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
1b4c0 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
1b4d0 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
1b4e0 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
1b4f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1b500 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
1b510 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
1b520 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
1b530 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1b540 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1b550 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
1b560 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
1b570 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
1b580 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
1b590 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
1b5a0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1b5b0 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
1b5c0 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
1b5d0 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
1b5e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1b5f0 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
1b600 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
1b610 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
1b620 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
1b630 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
1b640 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
1b650 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
1b660 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1b670 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
1b680 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1b690 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
1b6a0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1b6b0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1b6c0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1b6d0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1b6e0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
1b6f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1b700 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1b710 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b720 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1b730 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1b740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b750 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1b760 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1b770 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b780 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b790 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1b7a0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b7b0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1b7c0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b7d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b7e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1b7f0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1b800 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1b810 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b820 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1b830 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
1b840 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
1b850 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
1b860 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
1b870 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
1b880 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
1b890 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
1b8a0 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
1b8b0 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
1b8c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b8d0 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
1b8e0 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
1b8f0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
1b900 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
1b910 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
1b920 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1b930 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
1b940 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
1b950 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
1b960 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1b970 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1b980 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
1b990 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
1b9a0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
1b9b0 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
1b9c0 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
1b9d0 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
1b9e0 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1b9f0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
1ba00 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1ba10 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
1ba20 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1ba30 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1ba40 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
1ba50 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
1ba60 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1ba70 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
1ba80 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1ba90 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1baa0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1bab0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1bac0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
1bad0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1bae0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1baf0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1bb00 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1bb10 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1bb20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bb30 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1bb40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1bb50 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1bb60 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1bb70 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1bb80 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1bb90 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1bba0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
1bbb0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
1bbc0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1bbd0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
1bbe0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
1bbf0 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44   Query.** METHOD
1bc00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1bc10 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
1bc20 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
1bc30 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
1bc40 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
1bc50 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
1bc60 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
1bc70 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
1bc80 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
1bc90 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
1bca0 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
1bcb0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
1bcc0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
1bcd0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
1bce0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
1bcf0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
1bd00 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
1bd10 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
1bd20 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
1bd30 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
1bd40 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
1bd50 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
1bd60 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
1bd70 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
1bd80 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1bd90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
1bda0 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
1bdb0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
1bdc0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1bdd0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
1bde0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bdf0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
1be00 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
1be10 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
1be20 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
1be30 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
1be40 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
1be50 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
1be60 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
1be70 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
1be80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1be90 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
1bea0 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
1beb0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
1bec0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
1bed0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
1bee0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
1bef0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
1bf00 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
1bf10 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
1bf20 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
1bf30 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
1bf40 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
1bf50 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
1bf60 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1bf70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1bf80 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1bf90 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
1bfa0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1bfb0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
1bfc0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
1bfd0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
1bfe0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
1bff0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
1c000 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1c010 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
1c020 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
1c030 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
1c040 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1c050 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
1c060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c070 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
1c080 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
1c090 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1c0a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1c0b0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1c0c0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
1c0d0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
1c0e0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1c0f0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
1c100 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
1c110 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
1c120 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
1c130 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
1c140 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c150 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
1c160 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1c170 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1c180 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
1c190 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
1c1a0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1c1b0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
1c1c0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
1c1d0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
1c1e0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
1c1f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1c200 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
1c210 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
1c220 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1c230 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
1c240 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
1c250 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
1c260 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1c270 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1c280 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1c290 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
1c2a0 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20  eturns..*/.void 
1c2b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c2c0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1c2d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1c2e0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1c2f0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1c300 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1c310 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1c320 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1c330 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1c340 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1c350 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1c360 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1c370 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1c380 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1c390 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1c3a0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1c3b0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1c3c0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1c3d0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1c3e0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1c3f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c400 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1c410 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1c420 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1c430 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1c440 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1c450 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1c460 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1c470 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1c480 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1c490 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1c4a0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1c4b0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1c4c0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1c4d0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1c4e0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1c4f0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1c500 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1c510 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1c520 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1c530 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1c540 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1c550 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1c560 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1c570 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1c580 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1c590 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1c5a0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1c5b0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1c5c0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1c5d0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1c5e0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1c5f0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1c600 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1c610 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c620 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1c630 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1c640 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1c650 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1c660 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1c670 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1c680 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1c690 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1c6a0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1c6b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1c6c0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1c6d0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1c6e0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1c6f0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1c700 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1c710 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1c720 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1c730 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1c740 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1c750 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1c760 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1c770 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1c780 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1c790 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1c7a0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1c7b0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1c7c0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1c7d0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1c7e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1c7f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1c800 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1c810 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1c820 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1c830 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1c840 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1c850 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1c860 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1c870 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1c880 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1c890 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1c8a0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1c8b0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1c8c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1c8d0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1c8e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1c8f0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1c900 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1c910 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
1c920 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1c930 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1c940 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1c950 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1c960 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1c970 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1c980 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1c990 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1c9a0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
1c9b0 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
1c9c0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
1c9d0 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
1c9e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c9f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1ca00 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1ca10 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
1ca20 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1ca30 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
1ca40 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
1ca50 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
1ca60 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
1ca70 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1ca80 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
1ca90 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
1caa0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1cab0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1cac0 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
1cad0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
1cae0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
1caf0 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
1cb00 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1cb10 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
1cb20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1cb30 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
1cb40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1cb50 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
1cb60 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1cb70 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
1cb80 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1cb90 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1cba0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1cbb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1cbc0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
1cbd0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
1cbe0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
1cbf0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
1cc00 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
1cc10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
1cc20 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1cc30 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
1cc40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
1cc50 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1cc60 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1cc70 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1cc80 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
1cc90 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
1cca0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1ccb0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
1ccc0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
1ccd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1cce0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
1ccf0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1cd00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1cd10 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
1cd20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
1cd30 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
1cd40 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
1cd50 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
1cd60 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1cd70 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1cd80 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1cd90 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1cda0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1cdb0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1cdc0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1cdd0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
1cde0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
1cdf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1ce00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1ce10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1ce20 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1ce30 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1ce40 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1ce50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1ce60 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1ce70 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1ce80 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1ce90 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1cea0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1ceb0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1cec0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1ced0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1cee0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1cef0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1cf00 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1cf10 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1cf20 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1cf30 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1cf40 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1cf50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1cf60 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
1cf70 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
1cf80 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1cf90 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
1cfa0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
1cfb0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
1cfc0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
1cfd0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
1cfe0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
1cff0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
1d000 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
1d010 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
1d020 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1d030 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
1d040 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
1d050 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
1d060 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
1d070 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
1d080 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
1d090 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
1d0a0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
1d0b0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1d0c0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1d0d0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1d0e0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
1d0f0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
1d100 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1d110 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
1d120 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
1d130 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
1d140 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
1d150 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
1d160 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
1d170 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
1d180 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
1d190 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1d1a0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1d1b0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1d1c0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1d1d0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1d1e0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1d1f0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1d200 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1d210 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1d220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1d230 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1d240 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1d250 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1d260 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1d270 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1d280 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1d290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d2a0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1d2b0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1d2c0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1d2d0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1d2e0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1d2f0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1d300 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1d310 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1d320 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1d330 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1d340 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1d350 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1d360 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1d370 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1d380 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1d390 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1d3a0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1d3b0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1d3c0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1d3d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d3e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1d3f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d400 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1d410 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1d420 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1d430 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1d440 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1d450 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1d460 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1d470 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1d480 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1d490 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1d4a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d4b0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1d4c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1d4d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1d4e0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
1d4f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1d500 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1d510 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  ,int(*)(void*,in
1d520 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  t),void*);../*.*
1d530 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1d540 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1d550 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1d560 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1d570 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1d580 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1d590 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1d5a0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1d5b0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1d5c0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1d5d0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1d5e0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1d5f0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1d600 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1d610 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1d620 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1d630 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1d640 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1d650 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1d660 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1d670 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1d680 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1d690 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1d6a0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1d6b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1d6c0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1d6d0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1d6e0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1d6f0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1d700 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1d710 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1d720 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1d730 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1d740 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1d750 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1d760 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1d770 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1d780 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1d790 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1d7a0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1d7b0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1d7c0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1d7d0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1d7e0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1d7f0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1d800 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1d810 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1d820 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1d830 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1d840 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1d850 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1d860 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1d870 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1d880 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1d890 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1d8a0 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1d8b0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1d8c0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1d8d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1d8e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1d8f0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1d900 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1d910 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1d920 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d930 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1d940 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1d950 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1d960 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1d970 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1d980 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1d990 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1d9a0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1d9b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1d9c0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1d9d0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1d9e0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1d9f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1da00 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1da10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1da20 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1da30 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1da40 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1da50 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1da60 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1da70 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1da80 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1da90 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1daa0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1dab0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1dac0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1dad0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1dae0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1daf0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1db00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1db10 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1db20 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1db30 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1db40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1db50 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1db60 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1db70 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1db80 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1db90 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1dba0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1dbb0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1dbc0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1dbd0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1dbe0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1dbf0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1dc00 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1dc10 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1dc20 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1dc30 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1dc40 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1dc50 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1dc60 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1dc70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1dc80 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1dc90 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1dca0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1dcb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1dcc0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1dcd0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1dce0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1dcf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1dd00 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1dd10 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1dd20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1dd30 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1dd40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1dd50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1dd60 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1dd70 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1dd80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1dd90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1dda0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1ddb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1ddc0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1ddd0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1dde0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1ddf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1de00 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1de10 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1de20 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1de30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1de40 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1de50 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1de60 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1de70 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1de80 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1de90 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1dea0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1deb0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1dec0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1ded0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1dee0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1def0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1df00 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1df10 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1df20 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1df30 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1df40 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1df50 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1df60 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1df70 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1df80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1df90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dfa0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1dfb0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1dfc0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1dfd0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1dfe0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1dff0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1e000 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1e010 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1e020 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e030 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1e040 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e050 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1e060 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e070 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1e080 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1e090 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1e0a0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1e0b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1e0c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e0d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1e0e0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1e0f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1e100 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1e110 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e120 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1e130 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1e140 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1e150 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1e160 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1e170 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1e180 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1e190 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1e1a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1e1b0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1e1c0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1e1d0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1e1e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1e1f0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1e200 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1e210 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1e220 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1e230 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1e240 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1e250 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1e260 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1e270 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1e280 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1e290 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1e2a0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1e2b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e2c0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1e2d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1e2e0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1e2f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e300 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1e310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1e320 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1e330 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1e340 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1e350 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1e360 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1e370 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1e380 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1e390 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1e3a0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1e3b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1e3c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1e3d0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1e3e0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1e3f0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1e400 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1e410 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1e420 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1e430 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1e440 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1e450 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1e460 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1e470 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1e480 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1e490 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1e4a0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1e4b0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1e4c0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1e4d0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1e4e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1e4f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1e500 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1e510 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1e520 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1e530 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1e540 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1e550 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1e560 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1e570 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1e580 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1e590 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1e5a0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1e5b0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1e5c0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1e5d0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1e5e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1e5f0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1e600 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1e610 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1e620 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1e630 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1e640 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1e650 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1e660 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1e670 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1e680 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1e690 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1e6a0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1e6b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1e6c0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1e6d0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1e6e0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1e6f0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1e700 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1e710 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1e720 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1e730 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1e740 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1e750 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e760 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1e770 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f  of the common fo
1e780 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e790 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1e7a0 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72  ndard library pr
1e7b0 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20  intf() .** plus 
1e7c0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1e7d0 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1e7e0 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d  mats ([%q], [%Q]
1e7f0 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d  , [%w], and [%z]
1e800 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62  )..** See the [b
1e810 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1e820 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1e830 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a  for details..**.
1e840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e850 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1e860 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1e870 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1e880 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1e890 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1e8a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1e8b0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e  te3_malloc64()].
1e8c0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1e8d0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1e8e0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1e8f0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1e900 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1e910 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1e920 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e930 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1e940 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1e950 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e  alloc64()] is un
1e960 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1e970 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1e980 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1e990 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1e9a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1e9b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1e9c0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1e9d0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1e9e0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1e9f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ea00 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ea10 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ea20 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1ea30 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ea40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ea50 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1ea60 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1ea70 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1ea80 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1ea90 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1eaa0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1eab0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1eac0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1ead0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1eae0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1eaf0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1eb00 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1eb10 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1eb20 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1eb30 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1eb40 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1eb50 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1eb60 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1eb70 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1eb80 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1eb90 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1eba0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1ebb0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1ebc0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1ebd0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1ebe0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1ebf0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1ec00 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1ec10 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1ec20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1ec30 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1ec40 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1ec50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1ec60 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1ec70 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1ec80 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1ec90 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1eca0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1ecb0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1ecc0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1ecd0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1ece0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1ecf0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1ed00 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1ed10 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1ed20 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1ed30 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1ed40 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1ed50 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1ed60 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1ed70 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1ed80 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1ed90 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1eda0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1edb0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1edc0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1edd0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1ede0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1edf0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1ee00 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1ee10 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ntf()..**.** See
1ee20 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69   also:  [built-i
1ee30 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72  n printf()], [pr
1ee40 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74  intf() SQL funct
1ee50 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  ion].*/.char *sq
1ee60 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1ee70 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1ee80 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1ee90 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1eea0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1eeb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1eec0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1eed0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1eee0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1eef0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1ef00 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1ef10 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1ef20 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1ef30 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1ef40 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1ef50 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1ef60 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1ef70 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1ef80 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1ef90 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1efa0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1efb0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1efc0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1efd0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1efe0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1eff0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1f000 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f010 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1f020 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1f030 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1f040 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1f050 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1f060 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1f070 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1f080 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1f090 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1f0a0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1f0b0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1f0c0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1f0d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f0e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1f0f0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1f100 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1f110 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1f120 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1f130 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f140 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1f150 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1f160 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1f170 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1f180 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1f190 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1f1a0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1f1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f1c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1f1d0 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1f1e0 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1f1f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1f200 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1f210 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1f220 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1f230 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1f240 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1f250 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1f260 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1f270 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1f280 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f290 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1f2a0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1f2b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1f2c0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1f2d0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1f2e0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1f2f0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1f300 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1f310 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1f320 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1f330 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f340 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1f350 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1f360 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1f370 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1f380 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1f390 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1f3a0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1f3b0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1f3c0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1f3d0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1f3e0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1f3f0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1f400 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1f410 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1f420 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1f430 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1f440 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1f450 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f460 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1f470 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1f480 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1f490 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1f4a0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1f4b0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1f4c0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f4d0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f4e0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1f4f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1f500 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1f510 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1f520 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1f530 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1f540 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1f550 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1f560 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1f570 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1f580 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1f590 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f5a0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1f5b0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1f5c0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1f5d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1f5e0 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1f5f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f600 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f610 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1f620 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1f630 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1f640 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1f650 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1f660 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1f670 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1f680 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1f690 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1f6a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1f6b0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1f6c0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1f6d0 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1f6e0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1f6f0 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1f700 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1f710 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f720 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1f730 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1f740 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f750 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1f760 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1f770 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1f780 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1f790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f7a0 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1f7b0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1f7c0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1f7d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f7e0 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1f7f0 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1f800 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1f810 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1f820 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1f830 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f840 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1f850 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1f860 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1f870 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f880 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1f890 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1f8a0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1f8b0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1f8c0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1f8d0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1f8e0 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1f8f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1f900 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1f910 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f920 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f930 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1f940 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1f950 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f960 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1f970 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f980 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1f990 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1f9a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1f9b0 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1f9c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1f9d0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f9e0 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1f9f0 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1fa00 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1fa10 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1fa20 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1fa30 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1fa40 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1fa50 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1fa60 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1fa70 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1fa80 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1fa90 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1faa0 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1fab0 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1fac0 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1fad0 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1fae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1faf0 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1fb00 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1fb10 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1fb20 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1fb30 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1fb40 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1fb50 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1fb60 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1fb70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1fb80 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1fb90 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1fba0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1fbb0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1fbc0 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1fbd0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1fbe0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1fbf0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1fc00 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1fc10 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1fc20 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1fc30 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1fc40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1fc50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1fc60 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1fc70 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1fc80 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1fc90 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1fca0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1fcb0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1fcc0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1fcd0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1fce0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1fcf0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1fd00 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1fd10 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1fd20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1fd30 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1fd40 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1fd50 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1fd60 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1fd70 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1fd80 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1fd90 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1fda0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1fdb0 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1fdc0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1fdd0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1fde0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1fdf0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1fe00 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1fe10 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1fe20 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1fe30 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1fe40 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1fe50 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1fe60 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1fe70 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1fe80 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1fe90 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1fea0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1feb0 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1fec0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1fed0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1fee0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1fef0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1ff00 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1ff10 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1ff20 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1ff30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1ff40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ff50 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1ff60 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1ff70 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1ff80 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1ff90 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1ffa0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1ffb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1ffc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1ffd0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1ffe0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1fff0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
20000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
20010 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
20020 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
20030 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
20040 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
20050 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
20060 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
20070 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
20080 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20090 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
200a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
200b0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
200c0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
200d0 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
200e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
200f0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
20100 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20110 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
20120 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20130 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
20140 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
20150 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
20160 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
20170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
20180 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
20190 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
201a0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
201b0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
201c0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
201d0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
201e0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
201f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
20200 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
20210 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20220 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
20230 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
20240 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
20250 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
20260 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
20270 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
20280 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
20290 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
202a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
202b0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
202c0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
202d0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
202e0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
202f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20300 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20310 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20320 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
20330 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
20340 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20350 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
20360 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
20370 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
20380 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
20390 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
203a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
203b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
203c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
203d0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
203e0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
203f0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
20400 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
20410 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
20420 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
20430 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
20440 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
20450 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
20460 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
20470 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
20480 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
20490 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
204a0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
204b0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
204c0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
204d0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
204e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
204f0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
20500 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
20510 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
20520 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20530 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
20540 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20550 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
20560 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20570 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
20580 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
20590 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
205a0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
205b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
205c0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
205d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
205e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
205f0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20600 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20610 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20620 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20630 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
20640 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
20650 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
20660 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
20670 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
20680 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
20690 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
206a0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
206b0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
206c0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
206d0 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
206e0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
206f0 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20700 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20710 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20720 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20730 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
20740 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
20750 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
20760 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
20770 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
20780 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
20790 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
207a0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
207b0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
207c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
207d0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
207e0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
207f0 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
20800 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
20810 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
20820 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
20830 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
20840 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
20850 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
20860 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
20870 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
20880 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
20890 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
208a0 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
208b0 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
208c0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
208d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
208e0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
208f0 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
20900 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
20910 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
20920 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
20930 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20940 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
20950 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
20960 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
20970 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
20980 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
20990 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
209a0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
209b0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
209c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
209d0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
209e0 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
209f0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20a00 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20a10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20a20 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20a30 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20a40 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
20a50 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
20a60 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
20a70 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
20a80 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
20a90 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
20aa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20ab0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20ac0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20ae0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20af0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20b00 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20b10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20b20 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20b30 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20b40 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20b50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20b60 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20b70 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20b80 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20b90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20ba0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
20bb0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
20bc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20bd0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
20be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20bf0 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
20c00 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
20c10 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20c20 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20c30 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20c40 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
20c50 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
20c60 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20c70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20c80 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20c90 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
20ca0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20cb0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
20cc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
20cd0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
20ce0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
20cf0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
20d00 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20d10 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
20d20 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
20d30 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
20d40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20d50 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
20d60 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
20d70 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
20d80 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
20d90 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
20da0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
20db0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
20dc0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
20dd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
20de0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
20df0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
20e00 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
20e10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
20e20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
20e30 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
20e40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20e50 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20e60 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20e70 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
20e80 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20e90 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20ea0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
20eb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20ec0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
20ed0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
20ee0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
20ef0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
20f00 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
20f10 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20f20 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
20f30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20f40 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20f50 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20f60 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
20f70 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
20f80 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20f90 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
20fa0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
20fb0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
20fc0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
20fd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
20fe0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
21000 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
21010 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
21020 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
21030 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
21040 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
21050 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
21060 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
21070 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
21080 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
21090 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
210a0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
210b0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
210c0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
210d0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
210e0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
210f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
21100 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
21110 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
21120 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
21130 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
21140 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
21150 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
21160 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
21170 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
21180 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
21190 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
211a0 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
211b0 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
211c0 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
211d0 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
211e0 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
211f0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
21200 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21210 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
21220 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21230 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21240 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
21250 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21260 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
21270 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
21280 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21290 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
212a0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
212b0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
212c0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
212d0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
212e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
212f0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
21300 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
21310 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
21320 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
21330 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
21340 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
21350 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
21360 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
21370 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
21380 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
21390 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
213a0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
213b0 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
213c0 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
213d0 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
213e0 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
213f0 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
21400 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
21410 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
21420 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
21430 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
21440 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
21450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21460 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
21470 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
21480 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
21490 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
214a0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
214b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
214c0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
214d0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
214e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
214f0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21500 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21510 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21520 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21530 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
21540 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
21550 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
21560 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
21570 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
21580 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
21590 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
215a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
215b0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
215c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
215d0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
215e0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
215f0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21610 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21620 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21630 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21640 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
21650 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
21660 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
21670 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
21680 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
21690 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
216a0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
216b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
216c0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
216d0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
216e0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
216f0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21700 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21710 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21720 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21730 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21740 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
21750 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
21760 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
21770 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
21780 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
21790 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
217a0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
217b0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
217c0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
217d0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
217e0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
217f0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21800 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21810 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21820 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21830 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21840 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
21850 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
21860 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
21870 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
21880 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
21890 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
218a0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
218b0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
218c0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
218d0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
218e0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
218f0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21900 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21910 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21920 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21930 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21940 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
21950 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
21960 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
21970 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21980 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
21990 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
219a0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
219b0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
219c0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
219d0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
219e0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
219f0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21a00 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21a10 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21a20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21a30 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21a40 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21a50 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21a70 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
21a80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21a90 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
21aa0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
21ab0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21ac0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21ad0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21ae0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21af0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21b00 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21b10 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21b20 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
21b30 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
21b40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
21b50 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
21b60 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
21b70 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
21b80 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
21b90 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
21ba0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
21bb0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
21bc0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
21bd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
21be0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
21bf0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
21c00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21c10 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
21c20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
21c30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21c40 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
21c50 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
21c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21c70 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
21c80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
21c90 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
21ca0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
21cb0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
21cc0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
21cd0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
21ce0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
21cf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
21d00 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
21d10 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
21d20 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
21d30 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
21d40 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
21d50 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
21d60 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
21d70 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
21d80 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
21d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
21da0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
21db0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
21dc0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
21dd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21de0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21df0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21e00 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
21e10 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
21e20 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21e30 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
21e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
21e50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21e60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
21e70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21e80 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
21e90 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
21ea0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
21eb0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
21ec0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
21ed0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
21ee0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
21ef0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
21f00 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
21f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
21f20 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21f30 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
21f40 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
21f50 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
21f60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
21f70 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
21f80 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
21f90 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
21fa0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
21fb0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
21fc0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
21fd0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
21fe0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
21ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22000 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
22010 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
22020 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
22030 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
22040 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
22050 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
22060 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
22070 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
22080 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
22090 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
220a0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
220b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
220c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
220d0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
220e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
220f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
22100 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
22110 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
22120 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
22130 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
22140 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
22150 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
22160 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
22170 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
22180 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
22190 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
221a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
221b0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
221c0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
221d0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
221e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
221f0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
22200 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
22210 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
22220 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
22230 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
22240 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
22250 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
22260 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
22270 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
22280 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
22290 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
222a0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
222b0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
222c0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
222d0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
222e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
222f0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
22300 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
22310 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
22320 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22330 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22340 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
22350 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
22360 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
22370 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
22380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22390 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
223a0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
223b0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
223c0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
223d0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
223e0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
223f0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
22400 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
22410 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
22420 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
22430 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
22440 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
22450 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22460 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22470 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
22480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
22490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
224a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
224b0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
224c0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
224d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
224e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
224f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22500 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
22510 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
22520 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22530 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22540 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22550 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
22560 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
22570 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22580 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22590 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
225a0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
225b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
225c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
225d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
225e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
225f0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
22600 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22610 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22630 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22640 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
22650 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22680 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
22690 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
226a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
226b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
226c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
226d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
226e0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
226f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22720 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
22730 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
22740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22770 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
22780 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
22790 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
227a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
227b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227c0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
227d0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
227e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
227f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22810 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
22820 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
22830 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22860 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
22870 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
22880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
228a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
228b0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
228c0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
228d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
228e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22900 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
22910 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
22920 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22950 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
22960 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
22970 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22980 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22990 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
229a0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
229b0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
229c0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
229d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
229e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
229f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22a00 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
22a10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22a20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22a30 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
22a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22a50 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
22a60 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
22a70 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
22a80 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
22a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
22aa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22ab0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22ac0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22ad0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
22ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
22af0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22b00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22b10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
22b30 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
22b40 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
22b50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b70 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
22b80 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
22b90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22ba0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22bb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22bc0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
22bd0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
22be0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
22bf0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22c00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c10 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
22c20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
22c30 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22c40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22c50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c60 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
22c70 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
22c80 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22ca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22cb0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
22cc0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
22cd0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
22ce0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22d00 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
22d10 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
22d20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22d30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d50 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
22d60 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
22d70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22d80 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22da0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
22db0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
22dc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22dd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
22df0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
22e00 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
22e10 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
22e20 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
22e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
22e40 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
22e50 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
22e60 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
22e70 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
22e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
22e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22ea0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
22eb0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
22ec0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
22ed0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
22ee0 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
22ef0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22f00 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
22f10 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
22f20 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
22f30 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
22f40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
22f50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22f60 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
22f70 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
22f80 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
22f90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
22fa0 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
22fb0 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
22fc0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
22fd0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
22fe0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22ff0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
23000 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
23010 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
23020 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
23030 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
23040 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
23050 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23060 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
23070 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
23080 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
23090 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
230a0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
230b0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
230c0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
230d0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
230e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
230f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23100 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
23110 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23120 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
23130 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
23140 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
23150 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
23160 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
23170 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
23180 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
23190 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
231a0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
231b0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
231c0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
231d0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
231e0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
231f0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
23200 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
23210 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
23220 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
23230 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
23240 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
23250 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
23260 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
23270 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
23280 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
23290 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
232a0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
232b0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
232c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
232d0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
232e0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
232f0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
23300 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
23310 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23320 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
23330 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
23340 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
23350 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
23360 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
23370 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
23380 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
23390 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
233a0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
233b0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
233c0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
233d0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
233e0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
233f0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
23400 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
23410 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
23420 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
23430 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
23440 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
23450 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
23460 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
23470 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
23480 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
23490 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
234a0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
234b0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
234c0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
234d0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
234e0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
234f0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
23500 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
23510 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
23520 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
23530 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
23540 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
23550 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
23560 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
23570 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
23580 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
23590 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
235a0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
235b0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
235c0 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
235d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
235e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
235f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
23600 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
23610 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
23620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23630 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
23640 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
23650 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
23660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
23670 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
23680 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
23690 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
236a0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
236b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
236c0 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
236d0 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20  g logic.  The M 
236e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
236f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23700 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e  (D,M,X,P)] is an
23710 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
23720 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
23730 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
23740 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23750 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
23760 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
23770 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
23780 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
23790 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
237a0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
237b0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
237c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
237d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
237e0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
237f0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
23800 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
23810 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23820 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23830 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23840 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
23850 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
23860 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
23870 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
23880 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
23890 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
238a0 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
238b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
238c0 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
238d0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
238e0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
238f0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23900 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23910 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
23920 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
23930 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23940 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
23950 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23960 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
23970 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23980 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
23990 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
239a0 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
239b0 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
239c0 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
239d0 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
239e0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
239f0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
23a00 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
23a10 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
23a20 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
23a30 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
23a40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23a50 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
23a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
23a70 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
23a80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
23a90 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
23aa0 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
23ab0 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
23ac0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23ad0 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
23ae0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
23af0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
23b00 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
23b10 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
23b20 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
23b30 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
23b40 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
23b50 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
23b60 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
23b70 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
23b80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
23b90 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
23ba0 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
23bb0 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
23bc0 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
23bd0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
23be0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
23bf0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
23c00 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23c10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
23c20 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
23c30 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23c40 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23c50 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
23c60 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
23c70 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
23c80 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
23c90 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
23ca0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23cb0 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
23cc0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23cd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23ce0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23cf0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
23d00 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
23d10 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
23d20 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
23d30 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
23d40 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
23d50 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
23d60 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
23d70 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
23d80 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
23d90 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
23da0 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
23db0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
23dc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
23dd0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
23de0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
23df0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23e00 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
23e10 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23e20 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
23e30 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
23e40 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
23e50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
23e60 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
23e70 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
23e80 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
23e90 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23ea0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
23eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
23ec0 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
23ed0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
23ee0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
23ef0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
23f00 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
23f10 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
23f20 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
23f30 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
23f40 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23f50 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
23f60 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
23f70 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23f80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23f90 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
23fa0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
23fb0 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
23fc0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
23fd0 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
23fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23ff0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
24000 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
24010 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
24020 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
24030 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
24040 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
24050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24060 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
24070 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
24080 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
24090 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
240a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
240b0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
240c0 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
240d0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
240e0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
240f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
24100 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
24110 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
24120 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
24130 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
24140 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
24150 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
24160 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
24170 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
24180 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
24190 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
241a0 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
241b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
241c0 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
241d0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
241e0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
241f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
24200 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
24210 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
24220 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
24230 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
24240 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
24250 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
24260 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
24270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
24280 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
24290 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
242a0 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
242b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
242c0 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
242d0 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
242e0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
242f0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
24300 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
24310 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
24320 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
24330 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
24340 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
24350 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
24360 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
24370 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
24380 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
24390 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
243a0 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
243b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
243c0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
243d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
243e0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
243f0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
24400 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
24410 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
24420 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
24430 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
24440 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
24450 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
24460 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
24470 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
24480 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
24490 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
244a0 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
244b0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
244c0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
244d0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
244e0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
244f0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24500 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
24510 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
24520 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
24530 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
24540 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
24550 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
24560 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
24570 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
24580 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
24590 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
245a0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
245b0 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
245c0 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
245d0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
245e0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
245f0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
24600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
24610 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
24620 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
24630 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24640 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
24650 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
24660 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
24670 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
24680 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
24690 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
246a0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
246b0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
246c0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
246d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
246e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
246f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
24700 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
24710 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24720 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
24730 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
24740 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
24750 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
24760 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
24770 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
24780 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
24790 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
247a0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
247b0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
247c0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
247d0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
247e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
247f0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
24800 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
24810 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
24820 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
24830 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
24840 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
24850 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
24860 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
24870 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
24880 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
24890 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
248a0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
248b0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
248c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
248d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
248e0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
248f0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
24900 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24910 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
24920 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
24930 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
24940 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
24950 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
24960 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
24970 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
24980 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
24990 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
249a0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
249b0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
249c0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
249d0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
249e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
249f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
24a00 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
24a10 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
24a20 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
24a30 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
24a40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
24a50 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
24a60 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
24a70 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
24a80 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
24a90 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
24aa0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
24ab0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
24ac0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
24ad0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
24ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24af0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
24b00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24b10 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
24b20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24b30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
24b40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
24b50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
24b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24b70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
24b80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
24b90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
24ba0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
24bb0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24bc0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
24bd0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
24be0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
24bf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24c00 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
24c10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
24c20 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
24c30 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24c40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
24c50 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
24c60 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
24c70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
24c80 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
24c90 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
24ca0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
24cb0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
24cc0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
24cd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
24ce0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24cf0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
24d00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
24d10 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
24d20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
24d30 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
24d40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
24d50 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
24d60 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
24d70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
24d80 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
24d90 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
24da0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
24db0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
24dc0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
24dd0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
24de0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
24df0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
24e00 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
24e10 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
24e20 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
24e30 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
24e40 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
24e50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24e60 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
24e70 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
24e80 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
24e90 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
24ea0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
24eb0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
24ec0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
24ed0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
24ee0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
24ef0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24f00 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
24f10 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
24f20 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
24f30 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
24f40 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
24f50 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
24f60 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
24f70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
24f80 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
24f90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
24fa0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
24fb0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
24fc0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
24fd0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
24fe0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
24ff0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
25000 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
25010 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
25020 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
25030 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
25040 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
25050 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
25060 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
25070 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
25080 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
25090 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
250a0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
250b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
250c0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
250d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
250e0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
250f0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
25100 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
25110 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
25120 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
25130 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
25140 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
25150 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
25160 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
25170 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
25180 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
25190 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
251a0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
251b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
251c0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
251d0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
251e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
251f0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
25200 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
25210 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
25220 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
25230 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
25240 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
25250 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25260 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
25270 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25280 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
25290 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
252a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
252b0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
252c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
252d0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
252e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
252f0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
25300 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
25310 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25320 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25330 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25340 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
25350 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
25360 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
25370 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
25380 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
25390 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
253a0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
253b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
253c0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
253d0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
253e0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
253f0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
25400 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
25410 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
25420 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
25430 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
25440 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
25450 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
25460 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
25470 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
25480 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
25490 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
254a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
254b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
254c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
254d0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
254e0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
254f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
25500 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25510 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25520 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
25530 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
25540 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
25550 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
25560 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
25570 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
25580 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
25590 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
255a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
255b0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
255c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
255d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
255e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
255f0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
25600 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
25610 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
25620 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
25630 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
25640 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25650 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
25660 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
25670 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25680 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25690 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
256a0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
256b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
256c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
256d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
256e0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
256f0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
25700 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
25710 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
25720 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
25730 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
25740 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
25750 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
25760 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
25770 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
25780 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
25790 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
257a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
257b0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
257c0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
257d0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
257e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
257f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
25800 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
25810 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
25820 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
25830 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25840 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
25850 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25870 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
25880 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
25890 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
258a0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
258b0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
258c0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
258d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
258e0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
258f0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
25900 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25910 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
25920 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25940 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
25950 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
25960 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
25970 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
25980 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
25990 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
259a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
259b0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
259c0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
259d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
259e0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
259f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25a00 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25a10 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
25a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25a30 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
25a40 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
25a50 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
25a60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25a70 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
25a80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25a90 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
25aa0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
25ab0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
25ac0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25ad0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
25ae0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
25af0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
25b00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
25b10 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
25b20 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
25b30 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
25b40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25b50 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
25b60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25b70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
25b80 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
25b90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
25ba0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
25bb0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
25bc0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
25bd0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
25be0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
25bf0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25c00 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
25c10 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
25c20 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
25c30 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
25c40 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
25c50 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
25c60 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
25c70 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
25c80 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
25c90 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
25ca0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
25cb0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
25cc0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
25cd0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
25ce0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
25cf0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
25d00 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
25d10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
25d20 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
25d30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
25d40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
25d50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
25d60 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
25d70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
25d80 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
25d90 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
25da0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
25db0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25dc0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
25dd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
25de0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
25df0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
25e00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25e10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25e20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
25e30 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
25e40 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
25e50 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25e60 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25e70 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25e80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
25e90 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25ea0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
25eb0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
25ec0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
25ed0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
25ee0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
25ef0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
25f00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
25f10 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
25f20 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
25f30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
25f40 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69  ption..** URI fi
25f50 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
25f60 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
25f70 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
25f80 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
25f90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
25fa0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
25fb0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
25fc0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
25fd0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
25fe0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
25ff0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
26000 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
26010 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
26020 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
26030 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
26040 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
26050 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
26060 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
26070 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
26080 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
26090 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
260a0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
260b0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
260c0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
260d0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
260e0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
260f0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
26100 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
26110 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
26120 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26130 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
26140 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
26150 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
26160 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
26170 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
26180 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
26190 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
261a0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
261b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
261c0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
261d0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
261e0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
261f0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
26200 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
26210 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
26220 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
26230 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
26240 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
26250 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
26260 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
26270 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
26280 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
26290 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
262a0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
262b0 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
262c0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
262d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
262e0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
262f0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
26300 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
26310 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
26320 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
26330 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
26340 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
26350 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
26360 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
26370 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
26380 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
26390 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
263a0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
263b0 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
263c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
263d0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
263e0 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
263f0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
26400 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
26410 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
26420 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
26430 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
26440 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
26450 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
26460 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
26470 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
26480 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
26490 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
264a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
264b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
264c0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
264d0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
264e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
264f0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
26500 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
26510 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
26520 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
26530 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
26540 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
26550 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
26560 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
26570 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
26580 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26590 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
265a0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
265b0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
265c0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
265d0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
265e0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
265f0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
26600 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
26610 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
26620 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
26640 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26650 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
26660 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
26670 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26680 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
26690 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
266a0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
266b0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
266c0 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
266d0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
266e0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
266f0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
26700 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
26710 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26720 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
26730 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
26740 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
26750 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
26760 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
26770 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
26780 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
26790 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
267a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
267b0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
267c0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
267d0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
267e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
267f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
26800 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
26810 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
26820 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
26830 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26840 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
26850 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
26860 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
26870 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
26880 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
26890 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
268a0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
268b0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
268c0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
268d0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
268e0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
268f0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
26900 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
26910 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
26920 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
26930 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
26940 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
26950 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
26960 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
26970 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
26980 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
26990 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
269a0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
269b0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
269c0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
269d0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
269e0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
269f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26a00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26a10 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
26a20 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
26a30 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26a40 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
26a50 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
26a60 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
26a70 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
26a80 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
26a90 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26aa0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
26ab0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26ac0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
26ad0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
26ae0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
26af0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
26b00 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
26b10 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
26b20 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
26b30 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
26b40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
26b50 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
26b60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
26b70 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
26b80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26b90 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26ba0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
26bb0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
26bc0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
26bd0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
26be0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
26bf0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
26c00 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
26c10 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
26c20 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
26c30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26c40 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
26c50 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
26c60 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
26c70 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
26c80 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
26c90 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
26ca0 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
26cb0 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
26cc0 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
26cd0 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
26ce0 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
26cf0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
26d00 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
26d10 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
26d20 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
26d30 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
26d40 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
26d50 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
26d60 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
26d70 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
26d80 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
26d90 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
26da0 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
26db0 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
26dc0 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
26dd0 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
26de0 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
26df0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
26e00 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
26e10 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
26e20 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
26e30 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
26e40 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
26e50 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
26e60 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
26e70 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
26e80 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
26e90 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
26ea0 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
26eb0 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
26ec0 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
26ed0 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
26ee0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
26ef0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
26f00 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
26f10 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
26f20 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
26f30 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
26f40 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
26f50 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
26f60 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
26f70 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
26f80 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
26f90 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
26fa0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
26fb0 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
26fc0 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
26fd0 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
26fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26ff0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
27000 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
27010 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
27020 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
27030 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
27040 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
27050 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
27060 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
27070 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
27080 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
27090 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
270a0 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
270b0 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
270c0 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
270d0 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
270e0 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
270f0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
27100 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
27110 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
27120 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
27130 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
27140 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
27150 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
27160 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
27170 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
27180 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
27190 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
271a0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
271b0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
271c0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
271d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
271e0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
271f0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
27200 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
27210 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
27220 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
27230 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
27240 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
27250 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
27260 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
27270 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
27280 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
27290 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
272a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
272b0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
272c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
272d0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
272e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
272f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
27300 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
27310 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
27320 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
27330 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
27340 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
27350 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
27360 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
27370 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
27380 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
27390 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
273a0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
273b0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
273c0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
273d0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
273e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
273f0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
27400 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
27410 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
27420 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
27430 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
27440 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
27450 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
27460 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
27470 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
27480 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
27490 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
274a0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
274b0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
274c0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
274d0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
274e0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
274f0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
27500 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
27510 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
27520 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
27530 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
27540 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
27550 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
27560 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
27570 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
27580 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
27590 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
275a0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
275b0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
275c0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
275d0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
275e0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
275f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
27600 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
27610 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
27620 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
27630 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
27640 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
27650 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27660 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
27670 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
27680 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
27690 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
276a0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
276b0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
276c0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
276d0 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
276e0 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
276f0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
27700 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27710 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
27720 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
27730 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
27740 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
27750 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
27760 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
27770 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
27780 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27790 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
277a0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
277b0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
277c0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
277d0 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
277e0 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
277f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
27800 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
27810 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27820 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
27830 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
27840 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
27850 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
27860 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
27870 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
27880 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27890 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
278a0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
278b0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
278c0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
278d0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
278e0 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
278f0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
27900 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
27910 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
27920 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
27930 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
27940 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
27950 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
27960 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
27970 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
27980 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27990 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
279a0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
279b0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
279c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
279d0 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
279e0 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
279f0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
27a00 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
27a10 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
27a20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
27a30 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
27a40 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
27a50 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
27a60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27a70 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
27a80 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27a90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27aa0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
27ab0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
27ac0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
27ad0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
27ae0 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
27af0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
27b00 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
27b10 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
27b20 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
27b30 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
27b40 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
27b50 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
27b60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27b70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
27b80 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
27b90 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
27ba0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
27bb0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
27bc0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
27bd0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
27be0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
27bf0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
27c00 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
27c10 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
27c20 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
27c30 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
27c40 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
27c50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27c60 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
27c70 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
27c80 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
27c90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27ca0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27cb0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27cc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27cd0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27ce0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27cf0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27d00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
27d10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
27d20 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
27d30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
27d40 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
27d50 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
27d60 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27d70 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27d80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27d90 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
27da0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27db0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27dc0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27dd0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27de0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
27df0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27e00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
27e10 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
27e20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
27e30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
27e40 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
27e50 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
27e60 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
27e70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
27e80 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
27e90 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
27ea0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
27eb0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
27ec0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
27ed0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
27ee0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
27ef0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
27f00 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
27f10 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
27f20 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
27f30 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
27f40 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
27f50 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27f60 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27f70 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27f80 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27f90 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27fa0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
27fb0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
27fc0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
27fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
27fe0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
27ff0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
28000 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
28010 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
28020 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
28030 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
28040 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
28050 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
28060 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
28070 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
28080 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
28090 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
280a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
280b0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
280c0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
280d0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
280e0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
280f0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
28100 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
28110 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
28120 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
28130 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
28140 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
28150 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
28160 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28170 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
28180 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
28190 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
281a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
281b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
281c0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
281d0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
281e0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
281f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
28200 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
28210 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
28220 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
28230 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
28240 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28250 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
28260 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
28270 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
28280 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
28290 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
282a0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
282b0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
282c0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
282d0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
282e0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
282f0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
28300 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28310 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
28320 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
28330 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
28340 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
28350 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
28360 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
28370 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
28380 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
28390 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
283a0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
283b0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
283c0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
283d0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
283e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
283f0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
28400 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
28410 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
28420 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28430 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
28440 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
28450 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
28460 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
28470 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
28480 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
28490 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
284a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
284b0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
284c0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
284d0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
284e0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
284f0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
28500 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
28510 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
28520 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
28530 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
28540 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
28550 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28560 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28570 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
28580 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
28590 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
285a0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
285b0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
285c0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
285d0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
285e0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
285f0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
28600 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
28610 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
28620 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
28630 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
28640 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
28650 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
28660 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
28670 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
28680 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
28690 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
286a0 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
286b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
286c0 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
286d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
286e0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
286f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28700 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
28710 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28720 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
28730 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
28740 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
28750 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
28760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
28770 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
28780 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
28790 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
287a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
287b0 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
287c0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
287d0 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
287e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
287f0 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
28800 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
28810 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
28820 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
28830 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
28840 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
28850 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
28860 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
28870 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
28880 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
28890 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
288a0 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
288b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
288c0 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
288d0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
288e0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
288f0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28900 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
28910 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
28920 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
28930 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
28940 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
28950 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
28960 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
28970 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
28980 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
28990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
289a0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
289b0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
289c0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
289d0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
289e0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
289f0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
28a00 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
28a10 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
28a20 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
28a30 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
28a40 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
28a50 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
28a60 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
28a70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
28a80 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
28a90 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
28aa0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
28ab0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
28ac0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
28ad0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
28ae0 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
28af0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
28b00 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
28b10 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
28b20 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
28b30 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
28b40 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
28b50 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
28b60 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
28b70 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
28b80 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
28b90 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
28ba0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28bb0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28bc0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28bd0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28be0 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
28bf0 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
28c00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
28c10 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
28c20 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
28c30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
28c40 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
28c50 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
28c60 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
28c70 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
28c80 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
28c90 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
28ca0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
28cb0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
28cc0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
28cd0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
28ce0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
28cf0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
28d00 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
28d10 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
28d20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
28d30 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
28d40 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
28d50 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
28d60 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
28d70 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
28d80 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
28d90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
28da0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
28db0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
28dc0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
28dd0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
28de0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
28df0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
28e00 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
28e10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
28e20 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
28e30 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
28e40 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
28e50 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
28e60 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
28e70 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
28e80 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
28e90 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
28ea0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
28eb0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
28ec0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
28ed0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
28ee0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
28ef0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
28f00 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
28f10 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
28f20 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
28f30 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
28f40 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
28f50 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
28f60 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
28f70 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
28f80 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
28f90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
28fa0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
28fb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28fc0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
28fd0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
28fe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
28ff0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
29000 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
29010 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
29020 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
29030 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
29040 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
29050 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
29060 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
29070 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
29080 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
29090 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
290a0 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
290b0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
290c0 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
290d0 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
290e0 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
290f0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
29100 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
29110 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
29120 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
29130 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
29140 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
29150 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
29160 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29170 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
29180 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
29190 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
291a0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
291b0 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
291c0 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
291d0 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
291e0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
291f0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
29200 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29210 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
29220 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
29230 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
29240 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
29250 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29260 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
29270 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29280 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
29290 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
292a0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
292b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
292c0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
292d0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
292e0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
292f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
29300 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
29310 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
29320 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
29330 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
29340 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
29350 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
29360 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
29370 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
29380 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
29390 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
293a0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
293b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
293c0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
293d0 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
293e0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
293f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
29400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29410 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
29420 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29430 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
29440 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
29450 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
29460 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
29470 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
29480 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
29490 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
294a0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
294b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
294c0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
294d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
294e0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
294f0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
29500 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
29510 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
29520 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
29530 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
29540 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
29550 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
29560 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
29570 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
29580 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29590 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
295a0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
295b0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
295c0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
295d0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
295e0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
295f0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
29600 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
29610 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
29620 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
29630 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
29640 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
29650 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
29660 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
29670 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
29680 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
29690 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
296a0 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
296b0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
296c0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
296d0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
296e0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
296f0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
29700 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
29710 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
29720 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
29730 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
29740 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
29750 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
29760 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
29770 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
29780 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
29790 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
297a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
297b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
297c0 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
297d0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
297e0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
297f0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
29800 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
29810 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
29820 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
29830 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
29840 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
29850 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29860 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
29870 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
29880 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
29890 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
298a0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
298b0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
298c0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
298d0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
298e0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
298f0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
29900 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
29910 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
29920 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
29930 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
29940 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
29950 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
29960 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
29970 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
29980 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
29990 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
299a0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
299b0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
299c0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
299d0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
299e0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
299f0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
29a00 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
29a10 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
29a20 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
29a30 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
29a40 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
29a50 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
29a60 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29a70 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29a80 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
29a90 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
29aa0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
29ab0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
29ac0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
29ad0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
29ae0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
29af0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
29b00 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
29b10 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
29b20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
29b30 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
29b40 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
29b50 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
29b60 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
29b70 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
29b80 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
29b90 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
29ba0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
29bb0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
29bc0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
29bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
29be0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
29bf0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
29c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29c10 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
29c20 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
29c30 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
29c40 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
29c50 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
29c60 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
29c70 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
29c80 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
29c90 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
29ca0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
29cb0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
29cc0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29cd0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
29ce0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
29cf0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
29d00 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
29d10 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
29d20 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
29d30 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
29d40 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
29d50 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
29d60 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
29d70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29d80 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29d90 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
29da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29db0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
29dc0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
29dd0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
29de0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
29df0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29e00 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
29e10 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29e20 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
29e30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29e40 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
29e50 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
29e60 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
29e70 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29e80 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
29e90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29ea0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
29eb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29ec0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29ed0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
29ee0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
29ef0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
29f00 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
29f10 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
29f20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
29f30 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
29f40 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
29f50 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
29f60 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
29f70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29f80 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
29f90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29fa0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
29fb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29fc0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29fd0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
29fe0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
29ff0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a000 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a010 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
2a020 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a030 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a040 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
2a050 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a060 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
2a070 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
2a080 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
2a090 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a0a0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
2a0b0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a0c0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
2a0d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a0e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
2a0f0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
2a100 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
2a110 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
2a120 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
2a130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
2a140 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   If [sqlite3_pre
2a150 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
2a160 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
2a170 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74  tries to allocat
2a180 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65  e space for more
2a190 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20   than this many 
2a1a0 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20  opcodes.** in a 
2a1b0 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20  single prepared 
2a1c0 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51  statement, an SQ
2a1d0 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72  LITE_NOMEM error
2a1e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
2a1f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a200 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a210 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
2a220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2a230 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
2a240 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a250 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2a260 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
2a270 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2a280 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a290 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
2a2a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
2a2b0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
2a2c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a2d0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
2a2e0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
2a2f0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
2a300 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a310 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2a320 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
2a330 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a340 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2a350 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a360 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2a370 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
2a380 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
2a390 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
2a3a0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
2a3b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a3c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a3d0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
2a3e0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2a3f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2a400 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
2a410 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
2a420 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
2a430 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
2a440 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2a450 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
2a460 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a470 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2a480 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2a490 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
2a4a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a4b0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
2a4c0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
2a4d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a4e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
2a4f0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
2a500 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a510 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2a520 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
2a530 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a540 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
2a550 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
2a560 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
2a570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a580 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
2a590 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
2a5a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a5b0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
2a5c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a5d0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2a5e0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2a5f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2a600 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2a610 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
2a620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a630 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2a640 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2a650 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
2a660 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2a670 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a680 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
2a690 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2a6a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2a6b0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
2a6c0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
2a6d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2a6e0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
2a6f0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
2a700 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a710 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
2a720 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
2a730 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
2a740 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2a750 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
2a760 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2a770 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
2a780 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
2a790 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a7a0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
2a7b0 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
2a7c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a7d0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
2a7e0 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
2a7f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
2a800 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a  epare Flags.**.*
2a810 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2a820 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
2a830 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20   flags that can 
2a840 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  be passed into.*
2a850 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61  * "prepFlags" pa
2a860 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b  rameter of the [
2a870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a880 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  v3()] and.** [sq
2a890 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a8a0 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v3()] interfaces
2a8b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67  ..**.** New flag
2a8c0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2a8d0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2a8e0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
2a8f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
2a900 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2a910 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53  ISTENT]] ^(<dt>S
2a920 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2a930 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a  RSISTENT</dt>.**
2a940 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
2a950 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2a960 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e  NT flag is a hin
2a970 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70  t to the query p
2a980 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74  lanner.** that t
2a990 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2a9a0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65  ement will be re
2a9b0 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e  tained for a lon
2a9c0 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72  g time and.** pr
2a9d0 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61  obably reused ma
2a9e0 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74  ny times.)^ ^Wit
2a9f0 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20  hout this flag, 
2aa00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aa10 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  _v3()].** and [s
2aa20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aa30 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68  _v3()] assume th
2aa40 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
2aa50 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a  statement will .
2aa60 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20  ** be used just 
2aa70 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20  once or at most 
2aa80 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20  a few times and 
2aa90 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75  then destroyed u
2aaa0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2aab0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c  _finalize()] rel
2aac0 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68  atively soon. Th
2aad0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2aae0 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a  entation acts.**
2aaf0 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79   on this hint by
2ab00 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73   avoiding the us
2ab10 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20  e of [lookaside 
2ab20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f  memory] so as no
2ab30 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20  t to.** deplete 
2ab40 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72  the limited stor
2ab50 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
2ab60 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65  emory. Future ve
2ab70 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c  rsions of.** SQL
2ab80 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74  ite may act on t
2ab90 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65  his hint differe
2aba0 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ntly..** </dl>.*
2abb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2abc0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2abd0 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ENT             
2abe0 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x01../*.** CAP
2abf0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2ac00 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2ac10 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2ac20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2ac30 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2ac40 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2ac50 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2ac60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2ac70 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2ac80 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75  statement, it mu
2ac90 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
2aca0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
2acb0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
2acc0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
2acd0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f  ese routines.  O
2ace0 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  r, in other word
2acf0 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  s, these routine
2ad00 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75  s.** are constru
2ad10 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70  ctors for the [p
2ad20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad30 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  t] object..**.**
2ad40 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72   The preferred r
2ad50 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73  outine to use is
2ad60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ad70 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a  e_v2()].  The.**
2ad80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ad90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  e()] interface i
2ada0 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f  s legacy and sho
2adb0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2adc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2add0 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e  are_v3()] has an
2ade0 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67   extra "prepFlag
2adf0 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69  s" option that i
2ae00 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70  s used.** for sp
2ae10 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a  ecial purposes..
2ae20 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66  **.** The use of
2ae30 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72   the UTF-8 inter
2ae40 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72  faces is preferr
2ae50 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75  ed, as SQLite cu
2ae60 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20  rrently.** does 
2ae70 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e  all parsing usin
2ae80 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54  g UTF-8.  The UT
2ae90 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2aea0 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
2aeb0 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  as a convenience
2aec0 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2aed0 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79  terfaces work by
2aee0 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a   converting the.
2aef0 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e  ** input text in
2af00 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69  to UTF-8, then i
2af10 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72  nvoking the corr
2af20 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20  esponding UTF-8 
2af30 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2af40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
2af50 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
2af60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2af70 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
2af80 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
2af90 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2afa0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2afb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2afc0 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
2afd0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2afe0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
2aff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2b000 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
2b010 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
2b020 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
2b030 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
2b040 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2b050 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
2b060 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
2b070 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
2b080 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2b090 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f  pare(), sqlite3_
2b0a0 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a  prepare_v2(),.**
2b0b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b0c0 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74  pare_v3().** int
2b0d0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2b0e0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2b0f0 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69  repare16(), sqli
2b100 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b110 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b120 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2b130 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ) use UTF-16..**
2b140 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
2b150 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
2b160 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
2b170 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
2b180 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
2b190 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
2b1a0 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
2b1b0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
2b1c0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2b1d0 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
2b1e0 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
2b1f0 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
2b200 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
2b210 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
2b220 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
2b230 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
2b240 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
2b250 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
2b260 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
2b270 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
2b280 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
2b290 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
2b2a0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
2b2b0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
2b2c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b2d0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
2b2e0 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
2b2f0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
2b300 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
2b310 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
2b320 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
2b330 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
2b340 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2b350 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
2b360 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
2b370 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
2b380 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2b390 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
2b3a0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
2b3b0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
2b3c0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
2b3d0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
2b3e0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
2b3f0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
2b400 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
2b410 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
2b420 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
2b430 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
2b440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2b450 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
2b460 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
2b470 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
2b480 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
2b490 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
2b4a0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
2b4b0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
2b4c0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
2b4d0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
2b4e0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
2b4f0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
2b500 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
2b510 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
2b520 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
2b530 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
2b540 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
2b550 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
2b560 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
2b570 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2b580 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b590 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
2b5a0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2b5b0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
2b5c0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
2b5d0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
2b5e0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2b5f0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
2b600 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2b610 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
2b620 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
2b630 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2b640 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2b650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b660 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v2(), sqlite3_pr
2b670 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69  epare_v3(), sqli
2b680 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b690 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b6a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2b6b0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2b6c0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2b6d0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2b6e0 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20  s..** The older 
2b6f0 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69  interfaces (sqli
2b700 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
2b710 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2b720 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65  e16()).** are re
2b730 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
2b740 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2b750 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2b760 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2b770 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58  ..** ^In the "vX
2b780 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2b790 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b7a0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2b7b0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2b7c0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2b7d0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2b7e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2b7f0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2b800 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2b810 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2b820 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2b830 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2b840 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2b850 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2b860 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2b870 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2b880 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2b890 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2b8a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2b8b0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2b8c0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2b8d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2b8e0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2b8f0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2b900 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2b910 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2b920 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2b930 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2b940 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2b950 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2b960 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2b970 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2b980 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2b990 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2b9a0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2b9b0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2b9c0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2b9d0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2b9e0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2b9f0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2ba00 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2ba10 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2ba20 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2ba30 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2ba40 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2ba50 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2ba60 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2ba70 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2ba80 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2ba90 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2baa0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2bab0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2bac0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bad0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2bae0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2baf0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2bb00 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2bb10 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2bb20 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2bb30 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2bb40 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2bb50 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2bb60 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2bb70 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2bb80 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2bb90 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2bba0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2bbb0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2bbc0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2bbd0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2bbe0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2bbf0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2bc00 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2bc10 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2bc20 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2bc30 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2bc40 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2bc50 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2bc60 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2bc70 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2bc80 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2bc90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2bca0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2bcb0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2bcc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2bcd0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2bce0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2bcf0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2bd00 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2bd10 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2bd20 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2bd30 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2bd40 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2bd50 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2bd60 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2bd70 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2bd80 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2bd90 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2bda0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2bdb0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2bdc0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2bdd0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2bde0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2bdf0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2be00 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2be10 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2be20 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   </ol>.**.** <p>
2be30 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  ^sqlite3_prepare
2be40 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72  _v3() differs fr
2be50 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  om sqlite3_prepa
2be60 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20  re_v2() only in 
2be70 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78  having.** the ex
2be80 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61  tra prepFlags pa
2be90 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69  rameter, which i
2bea0 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f  s a bit array co
2beb0 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f  nsisting of zero
2bec0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74   or.** more of t
2bed0 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  he [SQLITE_PREPA
2bee0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51  RE_PERSISTENT|SQ
2bef0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20  LITE_PREPARE_*] 
2bf00 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20  flags.  ^The.** 
2bf10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bf20 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
2bf30 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65  orks exactly the
2bf40 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
2bf50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2bf60 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65   with a zero pre
2bf70 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2bf80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bf90 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2bfa0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bfb0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2bfc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2bfd0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2bfe0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2bff0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2c000 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c010 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c020 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c030 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c040 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c050 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c060 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c070 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c080 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c090 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c0a0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c0b0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2c0c0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2c0d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
2c0e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c0f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c100 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c120 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c130 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c140 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c150 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c160 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c170 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c180 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c1a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c1b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c1c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c1d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c1e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c1f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c200 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2c210 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c220 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v3(.  sqlite3 
2c230 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c240 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c250 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c260 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c270 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c280 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2c290 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c2b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c2c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c2d0 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c2e0 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2c2f0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c300 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c310 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c320 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c330 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c340 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c350 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c360 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c370 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c380 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c390 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c3a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
2c3b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c3c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c3d0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c3e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2c3f0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c400 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2c410 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c420 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c430 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c440 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c450 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c460 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c470 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c480 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c490 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c4a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c4b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c4c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c4d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c4e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c4f0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2c500 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c510 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c520 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2c530 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2c540 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2c550 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2c560 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2c570 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2c580 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2c590 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2c5a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2c5b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c5c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c5d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c5e0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2c5f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c600 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c610 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c620 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c630 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a  3_prepare16_v3(.
2c640 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c650 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c660 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c670 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2c680 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c690 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c6a0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2c6b0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2c6c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2c6d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2c6e0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2c6f0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2c700 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2c710 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2c720 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2c730 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2c740 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2c750 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2c760 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2c770 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2c780 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2c790 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2c7a0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2c7b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c7c0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2c7d0 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2c7e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c7f0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2c800 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2c810 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2c820 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2c830 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2c840 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2c850 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2c860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c870 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2c880 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
2c890 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c8a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2c8b0 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v3()],.** [sq
2c8c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c8d0 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
2c8e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2c8f0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2c900 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2c910 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2c920 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c930 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2c940 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2c950 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2c960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c970 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2c980 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2c990 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2c9a0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2c9b0 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2c9c0 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2c9d0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2c9e0 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2c9f0 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2ca00 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2ca10 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2ca20 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2ca30 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2ca40 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2ca50 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2ca60 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2ca70 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2ca80 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2ca90 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2caa0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2cab0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2cac0 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2cad0 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2cae0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2caf0 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2cb00 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2cb10 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2cb20 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2cb30 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2cb40 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2cb50 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2cb60 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2cb70 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2cb80 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2cb90 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2cba0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2cbb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2cbc0 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2cbd0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2cbe0 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2cbf0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2cc00 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2cc10 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2cc20 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2cc30 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2cc40 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2cc50 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2cc60 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2cc70 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2cc80 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2cc90 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2cca0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2ccb0 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2ccc0 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2ccd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2cce0 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2ccf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2cd00 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2cd10 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2cd20 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2cd30 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2cd40 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2cd50 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2cd60 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2cd70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2cd80 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2cd90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2cda0 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2cdb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2cdc0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2cdd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2cde0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2cdf0 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  tmt);.char *sqli
2ce00 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ce10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ce20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ce30 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ce40 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2ce50 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2ce60 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2ce70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ce80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ce90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2cea0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2ceb0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2cec0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2ced0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2cee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cef0 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2cf00 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2cf10 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2cf20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2cf30 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2cf40 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2cf50 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2cf60 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2cf70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2cf80 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2cf90 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2cfa0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2cfb0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2cfc0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2cfd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2cfe0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2cff0 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2d000 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2d010 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2d020 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2d030 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2d040 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2d050 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2d060 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2d070 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2d080 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2d090 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2d0a0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2d0b0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2d0c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2d0d0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2d0e0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2d0f0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2d100 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d110 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2d120 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2d130 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2d140 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2d150 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2d160 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2d170 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2d180 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2d190 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2d1a0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2d1b0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2d1c0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2d1d0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d1e0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2d1f0 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2d200 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2d210 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2d220 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2d230 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2d240 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2d250 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2d260 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2d270 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2d280 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2d290 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2d2a0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2d2b0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2d2c0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2d2d0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2d2e0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2d2f0 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2d300 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2d310 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2d320 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2d330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d340 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2d350 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2d360 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2d370 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d380 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2d390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d3a0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2d3b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d3c0 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2d3d0 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2d3e0 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2d3f0 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2d400 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2d410 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2d420 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2d430 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2d440 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2d450 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2d460 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2d470 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2d480 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2d490 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2d4a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2d4b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2d4c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d4d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d4e0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2d4f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2d500 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2d510 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2d520 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d540 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2d550 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d560 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2d570 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2d590 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2d5a0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2d5b0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2d5c0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2d5d0 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2d5e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2d5f0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2d600 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2d610 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2d620 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2d630 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d640 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2d650 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2d660 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2d670 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2d680 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2d690 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2d6a0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2d6b0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2d6c0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2d6d0 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2d6e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2d6f0 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2d700 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2d710 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2d720 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2d730 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2d740 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2d750 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2d760 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2d770 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2d780 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2d790 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2d7a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2d7b0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2d7c0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2d7d0 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2d7e0 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2d7f0 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2d800 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2d810 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2d820 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2d830 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2d840 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2d850 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2d860 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2d870 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2d880 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2d890 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2d8a0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2d8b0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2d8c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2d8d0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2d8e0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2d8f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d900 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2d910 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2d920 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d930 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2d940 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2d950 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2d960 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2d970 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2d980 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2d990 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2d9a0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2d9b0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2d9c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2d9d0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2d9e0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2d9f0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2da00 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2da10 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2da20 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2da30 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2da40 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2da50 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2da60 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2da70 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2da80 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2da90 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2daa0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2dab0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2dac0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2dad0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2dae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2daf0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2db00 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2db10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2db20 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2db30 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2db40 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2db50 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2db60 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2db70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2db80 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2db90 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2dba0 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2dbb0 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2dbc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2dbd0 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2dbe0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dbf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2dc00 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2dc10 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2dc20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2dc30 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2dc40 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2dc50 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2dc60 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2dc70 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2dc80 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2dc90 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2dca0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2dcb0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2dcc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2dcd0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2dce0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2dcf0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2dd00 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2dd10 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2dd20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2dd30 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2dd40 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2dd50 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2dd60 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2dd70 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2dd80 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2dd90 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2dda0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2ddb0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2ddc0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2ddd0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2dde0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2ddf0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2de00 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2de10 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2de20 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2de30 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2de40 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2de50 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2de60 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2de70 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2de80 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2de90 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2dea0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2deb0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2dec0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2ded0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2dee0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2def0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2df00 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2df10 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2df20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2df30 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2df40 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2df50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2df60 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2df70 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2df80 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2df90 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2dfa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dfb0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2dfc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2dfd0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2dfe0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2dff0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e000 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e010 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2e020 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a  d as arguments.*
2e030 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  * to [sqlite3_re
2e040 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b  sult_value()], [
2e050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2e060 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ue()], and.** [s
2e070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2e080 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2e090 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2e0a0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2e0b0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2e0c0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2e0d0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2e0e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e0f0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2e100 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e110 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33  e3_value sqlite3
2e120 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2e130 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2e140 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2e150 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2e160 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2e170 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2e180 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2e190 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2e1a0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2e1b0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2e1c0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2e1d0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2e1e0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2e1f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2e200 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e210 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e220 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2e230 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e240 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e250 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2e260 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2e270 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2e280 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e290 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2e2a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2e2b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2e2c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e2d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2e2e0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2e2f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e300 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2e310 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e320 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2e330 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e340 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2e350 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e360 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2e370 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2e380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2e390 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2e3a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e3b0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2e3c0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2e3d0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2e3e0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2e3f0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2e400 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2e410 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2e420 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2e430 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2e440 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e450 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2e460 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e470 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2e480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e490 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2e4a0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2e4b0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2e4c0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2e4d0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2e4e0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2e4f0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2e500 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2e510 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2e520 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2e530 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2e540 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2e550 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2e560 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2e570 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2e580 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2e590 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2e5a0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2e5b0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2e5c0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2e5d0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2e5e0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2e5f0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2e600 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2e610 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2e620 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2e630 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2e640 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2e650 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2e660 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2e670 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2e680 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2e690 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2e6a0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2e6b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2e6c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2e6d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2e6e0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2e6f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e700 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2e710 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2e720 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2e730 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e740 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2e750 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2e760 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2e770 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2e780 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2e790 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2e7a0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2e7b0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2e7c0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2e7d0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2e7e0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2e7f0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2e800 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2e810 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2e820 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2e830 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2e840 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2e850 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2e860 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e870 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2e880 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2e890 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2e8a0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2e8b0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2e8c0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2e8d0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2e8e0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2e8f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2e900 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2e910 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2e920 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2e930 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2e940 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2e950 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2e960 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2e970 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2e980 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2e990 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2e9a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2e9b0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2e9c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e9d0 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2e9e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2e9f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ea00 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2ea10 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2ea20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2ea30 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2ea40 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2ea50 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2ea60 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2ea70 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2ea80 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2ea90 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2eaa0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2eab0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2eac0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2ead0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2eae0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2eaf0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2eb00 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2eb10 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2eb20 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2eb30 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2eb40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2eb50 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2eb60 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2eb70 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2eb80 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2eb90 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2eba0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2ebb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2ebc0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2ebd0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2ebe0 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2ebf0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ec00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2ec10 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2ec20 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2ec30 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2ec40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2ec50 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2ec60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2ec70 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2ec80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ec90 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2eca0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2ecb0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2ecc0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2ecd0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2ece0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2ecf0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2ed00 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2ed10 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2ed20 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2ed30 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2ed40 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2ed50 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2ed60 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2ed70 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2ed80 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2ed90 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2eda0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2edb0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2edc0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2edd0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2ede0 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2edf0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2ee00 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2ee10 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2ee20 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2ee30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2ee40 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2ee50 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2ee60 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2ee70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2ee80 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2ee90 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2eea0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2eeb0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2eec0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2eed0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2eee0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2eef0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2ef00 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2ef10 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2ef20 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2ef30 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2ef40 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2ef50 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2ef60 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2ef70 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2ef80 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2ef90 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2efa0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2efb0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2efc0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2efd0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2efe0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2eff0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2f000 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2f010 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2f020 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2f030 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2f040 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2f050 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2f060 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2f070 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2f080 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2f090 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2f0a0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2f0b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f0c0 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2f0d0 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2f0e0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2f0f0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2f100 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2f110 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2f120 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2f130 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2f140 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2f150 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f160 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2f170 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f180 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f190 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2f1a0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2f1b0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2f1c0 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2f1d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2f1e0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2f1f0 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2f200 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2f210 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2f220 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2f230 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2f240 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2f260 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2f270 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2f280 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2f290 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2f2a0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2f2b0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2f2c0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2f2d0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2f2e0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2f2f0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2f300 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2f310 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2f320 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2f330 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2f340 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2f350 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2f360 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2f370 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2f380 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2f390 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2f3a0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2f3b0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2f3c0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2f3d0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2f3e0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2f3f0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54  h BLOB..**.** ^T
2f400 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f410 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c  pointer(S,I,P,T,
2f420 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65  D) routine cause
2f430 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d  s the I-th param
2f440 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70  eter in.** [prep
2f450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f460 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c  S to have an SQL
2f470 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20   value of NULL, 
2f480 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a  but to also be.*
2f490 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2f4a0 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20  h the pointer P 
2f4b0 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69  of type T.  ^D i
2f4c0 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
2f4d0 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20  pointer or.** a 
2f4e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
2f4f0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2f500 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20   for P. ^SQLite 
2f510 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a  will invoke the.
2f520 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  ** destructor D 
2f530 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
2f540 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e  gument of P when
2f550 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20   it is finished 
2f560 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65  using.** P.  The
2f570 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f   T parameter sho
2f580 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20  uld be a static 
2f590 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62  string, preferab
2f5a0 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c  ly a string.** l
2f5b0 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69  iteral. The sqli
2f5c0 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2f5d0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  () routine is pa
2f5e0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f  rt of the.** [po
2f5f0 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
2f600 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
2f610 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
2f620 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2f630 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2f640 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2f650 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2f660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2f670 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2f680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f690 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2f6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2f6b0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2f6c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2f6d0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2f6e0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2f6f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2f700 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2f710 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2f720 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2f730 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2f740 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2f750 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2f760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f770 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2f780 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2f790 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2f7a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2f7b0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2f7c0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2f7d0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2f7e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2f7f0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2f800 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2f810 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2f820 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2f830 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f840 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2f850 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2f860 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2f870 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2f880 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2f890 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2f8a0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2f8b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2f8c0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2f8d0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2f8e0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2f8f0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2f900 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2f910 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2f920 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2f930 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2f940 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2f950 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2f960 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2f970 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2f980 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2f990 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2f9a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2f9b0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2f9c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f9d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f9e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2f9f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2fa00 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2fa10 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2fa20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2fa30 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2fa40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fa50 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2fa60 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2fa70 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2fa80 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2fa90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2faa0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2fab0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2fac0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2fad0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2fae0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2faf0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2fb00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2fb10 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2fb20 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2fb30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2fb40 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2fb50 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2fb60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2fb70 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2fb80 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2fb90 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2fba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2fbb0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2fbc0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2fbd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2fbe0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2fbf0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2fc00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2fc10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fc20 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2fc30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2fc40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2fc50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2fc60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fc70 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2fc80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2fc90 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2fca0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2fcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fcc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2fcd0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2fce0 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
2fcf0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2fd00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fd10 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2fd20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2fd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
2fd40 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
2fd50 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
2fd60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64  const char*,void
2fd70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2fd80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2fd90 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2fda0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2fdb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2fdc0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2fdd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fde0 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2fdf0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2fe00 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2fe10 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2fe20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2fe30 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2fe40 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2fe50 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2fe60 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2fe70 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2fe80 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2fe90 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2fea0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2feb0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2fec0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2fed0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2fee0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2fef0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2ff00 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2ff10 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2ff20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ff30 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2ff40 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2ff50 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2ff60 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2ff70 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2ff80 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2ff90 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2ffa0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2ffb0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2ffc0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2ffd0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2ffe0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2fff0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
30000 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
30010 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
30020 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
30030 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
30040 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
30050 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
30060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30080 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30090 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
300a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
300b0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
300c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
300d0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
300e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
300f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30100 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30120 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
30130 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
30140 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30150 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30170 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
30180 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30190 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
301a0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
301b0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
301c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
301d0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
301e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
301f0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
30200 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
30210 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
30220 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
30230 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
30240 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
30250 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30260 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
30270 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
30280 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
30290 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
302a0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
302b0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
302c0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
302d0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
302e0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
302f0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
30300 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
30310 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
30320 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
30330 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
30340 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
30350 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
30360 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
30370 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
30380 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
30390 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
303a0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
303b0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
303c0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
303d0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
303e0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
303f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
30400 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30410 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
30420 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
30430 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
30440 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
30450 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
30460 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
30470 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
30480 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
30490 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
304a0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
304b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
304c0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
304d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
304e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
304f0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30500 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30510 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30520 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
30530 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30540 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
30550 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30560 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30570 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30580 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
30590 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
305a0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
305b0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
305c0 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
305d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
305e0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
305f0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
30600 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
30610 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
30620 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
30630 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
30640 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
30650 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
30660 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
30670 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30680 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
30690 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
306a0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
306b0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
306c0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
306d0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
306e0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
306f0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
30700 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
30710 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
30720 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
30730 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
30740 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30750 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30760 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30770 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30780 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30790 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
307a0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
307b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
307c0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
307d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
307e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
307f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30810 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
30820 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
30830 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
30840 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30850 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
30860 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
30870 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30880 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30890 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
308a0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
308b0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
308c0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
308d0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
308e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
308f0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
30900 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30910 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30920 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
30930 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
30940 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
30950 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
30960 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30970 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30980 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30990 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
309a0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
309b0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
309c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
309d0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
309e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
309f0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
30a00 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
30a10 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
30a20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
30a30 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
30a40 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
30a50 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
30a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30a70 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
30a80 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
30a90 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
30aa0 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
30ab0 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
30ac0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
30ad0 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
30ae0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
30af0 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
30b00 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
30b10 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
30b20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
30b30 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
30b40 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
30b50 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
30b60 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
30b70 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
30b80 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
30b90 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
30ba0 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
30bb0 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
30bc0 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
30bd0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30be0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30bf0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
30c00 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
30c10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30c20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30c30 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
30c40 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
30c50 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
30c60 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30c70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
30c80 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
30c90 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
30ca0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
30cb0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
30cc0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
30cd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
30ce0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
30cf0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
30d00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30d10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
30d20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
30d30 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
30d40 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
30d50 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
30d60 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30d70 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
30d80 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
30d90 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
30da0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30db0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30dc0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
30dd0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
30de0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
30df0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
30e00 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
30e10 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
30e20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
30e30 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
30e40 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
30e50 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
30e60 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
30e70 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
30e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30e90 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
30ea0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
30eb0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
30ec0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
30ed0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
30ee0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
30ef0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
30f00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30f10 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
30f20 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
30f30 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
30f40 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
30f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
30f60 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
30f70 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
30f80 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
30f90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
30fa0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
30fb0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
30fc0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
30fd0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
30fe0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
30ff0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
31000 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
31010 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
31020 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31030 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
31040 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
31050 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
31060 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31070 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
31080 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
31090 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
310a0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
310b0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
310c0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
310d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
310e0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
310f0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
31100 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
31110 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
31120 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
31130 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31160 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
31170 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
31180 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31190 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
311a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
311b0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
311c0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
311d0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
311e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
311f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31200 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
31210 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
31220 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31230 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
31240 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
31250 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
31260 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
31270 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
31280 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31290 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
312a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
312b0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
312c0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
312d0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
312e0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
312f0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
31300 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
31310 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
31320 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
31330 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
31340 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
31350 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
31360 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
31370 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31380 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
31390 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
313a0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
313b0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
313c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
313d0 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
313e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
313f0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
31400 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
31410 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
31420 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
31430 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
31440 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31450 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
31460 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
31470 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
31480 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
31490 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
314a0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
314b0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
314c0 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
314d0 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
314e0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
314f0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
31500 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31510 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
31520 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
31530 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
31540 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
31550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31560 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
31570 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31580 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31590 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
315a0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
315b0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
315c0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
315d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
315e0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
315f0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
31600 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
31610 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
31620 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
31630 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31640 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
31650 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31660 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
31670 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
31680 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
31690 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
316a0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
316b0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
316c0 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
316d0 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
316e0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
316f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31700 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
31710 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
31720 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
31730 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
31740 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
31750 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
31760 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
31770 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
31780 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
31790 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
317a0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
317b0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
317c0 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
317d0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
317e0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
317f0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
31800 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
31810 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
31820 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
31830 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
31840 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
31850 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
31860 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
31870 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31880 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
31890 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
318a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
318b0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
318c0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
318d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
318e0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
318f0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
31900 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
31910 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
31920 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31930 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
31940 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
31950 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
31960 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
31970 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
31980 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31990 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
319a0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
319b0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
319c0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
319d0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
319e0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
319f0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31a00 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31a10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31a20 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
31a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31a40 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31a50 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31a60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31a70 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31a80 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
31a90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31aa0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31ab0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
31ac0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
31ad0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
31ae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31af0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
31b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31b10 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
31b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
31b30 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
31b40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31b50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31b60 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
31b70 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31b80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
31b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
31ba0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
31bb0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
31bc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31bd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31be0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
31bf0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
31c00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31c10 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
31c20 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
31c30 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
31c40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
31c50 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
31c60 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
31c70 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
31c80 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
31c90 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
31ca0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
31cb0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
31cc0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
31cd0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
31ce0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
31cf0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
31d00 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
31d10 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
31d20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
31d30 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
31d40 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
31d50 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
31d60 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
31d70 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
31d80 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
31d90 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
31da0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
31db0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
31dc0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
31dd0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
31de0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
31df0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
31e00 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
31e10 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
31e20 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
31e30 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
31e40 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
31e50 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
31e60 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
31e70 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
31e80 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
31e90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31ea0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
31eb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
31ec0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
31ed0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
31ee0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
31ef0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
31f00 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
31f10 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
31f20 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
31f30 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
31f40 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
31f50 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
31f60 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
31f70 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
31f80 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
31f90 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
31fa0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
31fb0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
31fc0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
31fd0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
31fe0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
31ff0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
32000 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
32010 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
32020 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
32030 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
32040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32050 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
32060 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
32070 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32080 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
32090 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
320a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
320b0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
320c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
320d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
320e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
320f0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
32100 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
32110 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
32120 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
32130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32140 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32150 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32170 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
32180 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32190 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
321a0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
321b0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
321c0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
321d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
321e0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
321f0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
32200 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
32210 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
32220 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
32230 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
32240 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
32250 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
32260 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
32270 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
32280 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
32290 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
322a0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
322b0 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
322c0 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
322d0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
322e0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
322f0 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
32300 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
32310 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32320 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32330 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
32340 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32350 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
32360 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
32370 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
32380 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32390 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
323a0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
323b0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
323c0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
323d0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
323e0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
323f0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
32400 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
32410 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
32420 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
32430 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
32440 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
32450 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
32460 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
32470 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
32480 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
32490 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
324a0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
324b0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
324c0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
324d0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
324e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
324f0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
32500 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
32510 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
32520 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
32530 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
32540 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
32550 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
32560 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
32570 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
32580 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
32590 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
325a0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
325b0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
325c0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
325d0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
325e0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
325f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
32600 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
32610 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
32620 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
32630 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
32640 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
32650 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
32660 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
32670 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
32680 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
32690 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
326a0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
326b0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
326c0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
326d0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
326e0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
326f0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
32700 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
32710 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
32720 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
32730 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
32740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32750 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
32760 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
32770 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
32780 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
32790 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
327a0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
327b0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
327c0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
327d0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
327e0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
327f0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
32800 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
32810 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
32820 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
32830 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
32840 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
32850 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
32860 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
32870 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32880 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
32890 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
328a0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
328b0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
328c0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
328d0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
328e0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
328f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
32900 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
32910 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
32920 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32930 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32940 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
32950 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
32960 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
32970 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32980 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
32990 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
329a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
329b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
329c0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
329d0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
329e0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
329f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
32a00 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
32a10 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
32a20 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
32a30 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
32a40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32a50 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
32a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32a70 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
32a80 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
32a90 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32aa0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
32ab0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
32ac0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
32ad0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
32ae0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
32af0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
32b00 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
32b10 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
32b20 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
32b30 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
32b40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32b50 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
32b60 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
32b70 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
32b80 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
32b90 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
32ba0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
32bb0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
32bc0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
32bd0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
32be0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
32bf0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
32c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32c10 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
32c20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
32c30 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
32c40 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
32c50 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
32c60 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
32c70 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
32c80 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
32c90 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
32ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
32cb0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
32cc0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
32cd0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
32ce0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
32cf0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
32d00 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
32d10 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
32d20 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
32d30 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
32d40 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
32d50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32d60 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
32d70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
32d80 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
32d90 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
32da0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
32db0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
32dc0 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
32dd0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
32de0 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
32df0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
32e00 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
32e10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
32e20 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
32e30 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
32e40 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
32e50 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
32e60 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
32e70 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
32e80 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
32e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
32ea0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
32eb0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
32ec0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
32ed0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
32ee0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
32ef0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
32f00 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
32f10 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
32f20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
32f30 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
32f40 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
32f50 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
32f60 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
32f70 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
32f80 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
32f90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32fa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
32fb0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
32fc0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
32fd0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
32fe0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
32ff0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
33000 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
33010 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
33020 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
33030 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
33040 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
33050 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33060 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33070 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
33080 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
33090 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
330a0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
330b0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
330c0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
330d0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
330e0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
330f0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
33100 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
33110 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
33120 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
33130 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
33140 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
33150 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
33160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
33170 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33180 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
33190 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
331a0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
331b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
331c0 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
331d0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
331e0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
331f0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
33200 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
33210 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
33220 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
33230 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
33240 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
33250 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
33260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
33270 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
33280 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
33290 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
332a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
332b0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
332c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
332d0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
332e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
332f0 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
33300 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33310 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33320 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33330 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33340 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
33350 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
33360 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
33370 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33380 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
33390 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
333a0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
333b0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
333c0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
333d0 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
333e0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
333f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
33400 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
33410 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
33420 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
33430 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
33440 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
33450 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
33460 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33470 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
33480 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
33490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
334a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
334b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
334c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
334d0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
334e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
334f0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
33500 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
33510 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
33520 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33530 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
33540 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
33550 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
33560 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33570 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
33580 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
33590 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
335a0 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
335b0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
335c0 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
335d0 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
335e0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
335f0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
33600 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
33610 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
33620 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
33630 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33640 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33650 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33660 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
33670 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33690 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
336a0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
336b0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
336c0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
336d0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
336e0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
336f0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
33700 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
33710 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33720 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33730 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
33740 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
33750 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
33760 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
33770 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
33780 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
33790 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
337a0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
337b0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
337c0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
337d0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
337e0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
337f0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
33800 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33810 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
33820 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
33830 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
33840 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
33850 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
33860 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
33870 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
33880 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
33890 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
338a0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
338b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
338c0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
338d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
338e0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
338f0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
33900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33910 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
33920 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
33930 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
33940 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
33950 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
33960 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
33970 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
33980 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
33990 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
339a0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
339b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
339c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
339d0 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
339e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
339f0 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
33a00 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
33a10 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
33a20 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
33a30 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
33a40 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
33a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33a60 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
33a70 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
33a80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
33aa0 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
33ab0 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
33ac0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33ae0 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
33af0 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
33b00 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
33b10 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33b20 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
33b30 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
33b40 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
33b50 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33b60 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33b70 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
33b80 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
33b90 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
33ba0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33bb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
33bc0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
33bd0 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
33be0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
33c00 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
33c10 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
33c20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
33c30 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
33c40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33c50 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
33c60 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
33c70 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
33c80 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
33c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33ca0 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
33cb0 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
33cc0 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
33cd0 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
33ce0 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
33cf0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33d00 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
33d10 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
33d20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
33d30 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
33d40 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
33d50 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
33d60 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33d70 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
33d80 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
33d90 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
33da0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
33db0 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
33dc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
33dd0 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
33de0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
33df0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
33e00 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
33e10 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
33e20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
33e30 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
33e40 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
33e50 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
33e60 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
33e70 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
33e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33e90 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
33ea0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
33eb0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
33ec0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
33ed0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
33ee0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33ef0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
33f00 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
33f10 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
33f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
33f30 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
33f40 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
33f50 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
33f60 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
33f70 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
33f80 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
33f90 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
33fa0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
33fb0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
33fc0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
33fd0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
33fe0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
33ff0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
34000 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
34010 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
34020 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
34030 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
34040 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
34050 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
34060 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
34070 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
34080 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
34090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
340a0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
340b0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
340c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
340d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
340e0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
340f0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
34100 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
34110 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
34120 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34130 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
34140 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
34150 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
34160 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34170 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
34180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34190 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
341a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
341b0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
341c0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
341d0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
341e0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
341f0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
34200 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34210 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
34220 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
34230 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34240 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
34250 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
34260 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
34270 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
34280 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
34290 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
342a0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
342b0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
342c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
342d0 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
342e0 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
342f0 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
34300 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
34310 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
34320 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
34330 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
34340 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
34350 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
34360 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
34370 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
34380 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
34390 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
343a0 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
343b0 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
343c0 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
343d0 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
343e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
343f0 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
34400 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
34410 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
34420 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
34430 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
34440 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
34450 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34470 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
34480 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
34490 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
344a0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
344b0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
344c0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
344d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
344e0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
344f0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
34500 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
34510 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
34520 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
34530 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
34540 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
34550 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
34560 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
34570 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
34580 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
34590 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
345a0 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
345b0 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
345c0 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
345d0 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
345e0 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
345f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
34600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34610 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
34620 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
34630 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
34640 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
34650 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
34660 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
34670 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
34680 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
34690 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
346a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
346b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
346c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
346d0 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
346e0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
346f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
34700 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
34710 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34720 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34730 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
34740 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
34750 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
34760 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
34770 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
34780 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34790 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
347a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
347b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
347c0 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
347d0 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
347e0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
347f0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34800 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
34810 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
34820 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
34830 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34850 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
34860 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34870 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34880 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34890 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
348a0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
348b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
348c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
348d0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
348e0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
348f0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
34900 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34910 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34920 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34930 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34940 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34950 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
34960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34970 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34980 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34990 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
349a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
349b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
349c0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
349d0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
349e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
349f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34a00 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
34a10 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34a20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34a30 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
34a40 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
34a50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34a60 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
34a70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34a90 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
34aa0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
34ab0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34ac0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
34ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34ae0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
34af0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
34b00 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
34b10 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
34b20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34b30 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
34b40 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
34b50 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
34b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34b70 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
34b80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
34b90 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
34ba0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
34bb0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
34bc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
34bd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34be0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
34bf0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
34c00 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
34c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34c20 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
34c30 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
34c40 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
34c50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
34c60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
34c70 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
34c80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
34c90 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
34ca0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
34cb0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
34cc0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
34cd0 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
34ce0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
34cf0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
34d00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34d10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
34d20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34d30 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
34d40 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
34d50 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
34d60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
34d70 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
34d80 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
34d90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
34da0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
34db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34dc0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
34dd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
34de0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
34df0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
34e00 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
34e10 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
34e20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
34e30 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
34e40 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
34e50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
34e60 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
34e70 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
34e80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
34e90 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
34ea0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
34eb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34ec0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
34ed0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
34ee0 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
34ef0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
34f00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
34f10 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
34f20 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
34f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
34f40 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
34f50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34f60 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
34f70 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
34f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34f90 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
34fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
34fb0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
34fc0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
34fd0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
34fe0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
34ff0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
35000 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
35010 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
35020 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
35030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
35040 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
35050 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
35060 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
35070 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
35080 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
35090 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
350a0 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
350b0 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
350c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
350d0 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
350e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
350f0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
35100 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
35110 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
35120 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
35130 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
35140 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35150 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
35160 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
35170 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
35180 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
35190 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
351a0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
351b0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
351c0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
351d0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
351e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
351f0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
35200 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
35210 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
35220 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
35230 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
35240 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
35250 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
35260 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
35270 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
35280 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
35290 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
352a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
352b0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
352c0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
352d0 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
352e0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
352f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35300 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35310 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
35320 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35330 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35340 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35350 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
35360 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
35370 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
35380 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
35390 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
353a0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
353b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
353c0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
353d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
353e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
353f0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35400 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
35410 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
35420 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
35430 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
35440 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
35450 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
35460 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
35470 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35480 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35490 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
354a0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
354b0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
354c0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
354d0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
354e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
354f0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
35500 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
35510 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
35520 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
35530 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35540 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35550 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
35560 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35570 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35580 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35590 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
355a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
355b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
355c0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
355d0 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
355e0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
355f0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
35600 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
35610 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
35620 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35630 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35640 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35650 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
35660 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35670 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35680 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35690 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
356a0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
356b0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
356c0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
356d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
356e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
356f0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
35700 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
35710 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
35720 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
35730 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35740 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
35750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35760 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
35770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35780 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
35790 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
357a0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
357b0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
357c0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
357d0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
357e0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
357f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35800 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35810 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
35820 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35830 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
35840 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35850 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35860 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
35870 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
35880 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
35890 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
358a0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
358b0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
358c0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
358d0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
358e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
358f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35910 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
35920 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35930 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35940 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
35950 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
35960 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35970 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
35980 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
35990 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
359a0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
359b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
359c0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
359d0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
359e0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
359f0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
35a00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
35a10 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
35a20 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
35a30 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
35a40 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
35a50 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
35a60 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
35a70 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
35a80 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
35a90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35aa0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
35ab0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
35ac0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
35ad0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
35ae0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
35af0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
35b00 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
35b10 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
35b20 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
35b30 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
35b40 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
35b50 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
35b60 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
35b70 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
35b80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
35b90 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
35ba0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
35bb0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
35bc0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
35bd0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
35be0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
35bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35c00 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
35c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35c20 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
35c30 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
35c40 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
35c50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
35c60 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
35c70 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
35c80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35c90 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
35ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35cb0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
35cc0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
35cd0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
35ce0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
35cf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
35d00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
35d10 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
35d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35d30 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
35d40 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
35d50 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
35d60 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
35d70 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
35d80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
35d90 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35da0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
35db0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
35dc0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
35dd0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
35de0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
35df0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
35e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35e10 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
35e20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
35e30 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
35e40 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
35e50 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35e60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
35e70 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
35e80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35e90 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
35ea0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
35eb0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
35ec0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
35ed0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
35ee0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
35ef0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
35f00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
35f10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
35f20 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
35f30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
35f40 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
35f50 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
35f60 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
35f70 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
35f80 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
35f90 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
35fa0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
35fb0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
35fc0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
35fd0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
35fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35ff0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
36000 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
36010 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
36020 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36030 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
36040 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
36050 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
36060 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36070 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
36080 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
36090 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
360a0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
360b0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
360c0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
360d0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
360e0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
360f0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
36100 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36110 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
36120 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
36130 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
36140 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36170 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
36180 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36190 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
361a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
361b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
361c0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
361d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
361e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
361f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36200 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
36210 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36220 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36230 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
36240 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
36250 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36260 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
36270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36280 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
36290 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
362a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
362b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
362c0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
362d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
362e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
362f0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
36300 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36310 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36320 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
36330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36340 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36350 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36360 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36370 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
36380 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36390 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
363a0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
363b0 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
363c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
363d0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
363e0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
363f0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
36400 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
36410 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
36420 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36430 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36440 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36450 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36460 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
36470 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
36480 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36490 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
364a0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
364b0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
364c0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
364d0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
364e0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
364f0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
36500 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36510 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
36520 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36530 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36540 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36550 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36560 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36570 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36580 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36590 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
365a0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
365b0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
365c0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
365d0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
365e0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
365f0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
36600 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
36610 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
36620 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
36630 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36640 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36650 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36660 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36670 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36680 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36690 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
366a0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
366b0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
366c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
366d0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
366e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
366f0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36700 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36720 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
36730 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36740 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36750 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36760 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36770 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36780 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36790 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
367a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
367b0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
367c0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
367d0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
367e0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
367f0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
36800 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
36810 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
36820 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
36830 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36840 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36860 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
36870 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
36880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36890 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
368a0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
368b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
368c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
368d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
368e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
368f0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36900 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36910 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36920 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36930 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36940 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
36950 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
36960 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
36970 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
36980 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
36990 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
369a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
369b0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
369c0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
369d0 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
369e0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
369f0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36a00 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36a10 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36a20 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36a30 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36a40 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
36a50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36a60 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
36a70 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
36a80 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
36a90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
36aa0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36ab0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
36ac0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
36ad0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
36ae0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
36af0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
36b00 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
36b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36b20 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
36b30 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
36b40 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
36b50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
36b60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36b70 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
36b80 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36b90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36ba0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
36bb0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
36bc0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
36bd0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
36be0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
36bf0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
36c00 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
36c10 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
36c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36c30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
36c40 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
36c50 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
36c60 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
36c70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
36c80 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
36c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36ca0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
36cb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
36cc0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
36cd0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36ce0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
36cf0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
36d00 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
36d10 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
36d20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
36d30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
36d40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36d50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
36d60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
36d70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36d80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
36d90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36da0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
36db0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
36dc0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
36dd0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
36de0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
36df0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
36e00 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
36e10 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
36e20 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
36e30 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
36e40 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
36e50 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
36e60 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
36e70 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
36e80 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
36e90 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
36ea0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
36eb0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
36ec0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
36ed0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
36ee0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
36ef0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
36f00 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
36f10 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
36f20 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
36f30 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
36f40 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36f50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
36f60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
36f70 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
36f80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36f90 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
36fa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
36fb0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
36fc0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
36fd0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
36fe0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
36ff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
37000 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37010 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37020 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
37030 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
37040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
37050 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37060 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
37070 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37080 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
37090 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
370a0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
370b0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
370c0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
370d0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
370e0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
370f0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
37100 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
37110 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
37120 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
37130 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
37140 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
37150 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
37160 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
37170 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
37180 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
37190 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
371a0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
371b0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
371c0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
371d0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
371e0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
371f0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
37200 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
37210 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
37220 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
37230 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37240 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
37250 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
37260 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
37270 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
37280 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37290 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
372a0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
372b0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
372c0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
372d0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
372e0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
372f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
37300 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
37310 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
37320 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
37330 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
37340 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
37350 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
37360 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
37370 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
37380 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
37390 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
373a0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
373b0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
373c0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
373d0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
373e0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
373f0 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
37400 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
37410 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
37420 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
37430 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
37440 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
37450 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
37460 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37470 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
37480 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
37490 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
374a0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
374b0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
374c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
374d0 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
374e0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
374f0 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
37500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37510 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
37520 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
37530 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
37540 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
37550 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37560 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
37570 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
37580 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
37590 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
375a0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
375b0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
375c0 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
375d0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
375e0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
375f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
37600 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
37610 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
37620 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
37630 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
37640 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
37650 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37660 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
37670 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37680 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
37690 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
376a0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
376b0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
376c0 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
376d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
376e0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
376f0 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
37700 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
37710 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
37720 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
37730 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
37740 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
37750 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
37760 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
37770 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
37780 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
37790 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
377a0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
377b0 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
377c0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
377d0 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
377e0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
377f0 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
37800 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
37810 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
37820 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
37830 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
37840 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
37850 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
37860 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
37870 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
37880 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
37890 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
378a0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
378b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
378c0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
378d0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
378e0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
378f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
37900 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
37910 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
37920 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
37930 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
37940 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
37950 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
37960 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
37970 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
37980 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
37990 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
379a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
379b0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
379c0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
379d0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
379e0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
379f0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
37a00 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
37a10 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
37a20 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
37a30 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
37a40 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
37a50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37a60 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37a70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
37a80 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
37a90 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
37aa0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
37ab0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
37ac0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
37ad0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
37ae0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
37af0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
37b00 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
37b10 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
37b20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
37b30 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
37b40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
37b50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37b60 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
37b70 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
37b80 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
37b90 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
37ba0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37bb0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
37bc0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
37bd0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
37be0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
37bf0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
37c00 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
37c10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
37c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
37c30 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
37c40 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
37c50 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
37c60 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
37c70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37c80 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
37c90 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
37ca0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
37cb0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
37cc0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
37cd0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
37ce0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
37cf0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
37d00 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
37d10 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
37d20 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
37d30 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
37d40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
37d50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37d60 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
37d70 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
37d80 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
37d90 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
37da0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
37db0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
37dc0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
37dd0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
37de0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
37df0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
37e00 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
37e10 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
37e20 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
37e30 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
37e40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37e50 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
37e60 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
37e70 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
37e80 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
37e90 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
37ea0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
37eb0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
37ec0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
37ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
37ee0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
37ef0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
37f00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
37f10 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
37f20 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
37f30 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
37f40 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
37f50 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
37f60 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
37f70 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
37f80 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
37f90 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
37fa0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
37fb0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
37fc0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
37fd0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
37fe0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
37ff0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
38000 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
38010 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
38020 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
38030 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
38040 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
38050 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
38060 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
38070 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
38080 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
38090 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
380a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
380b0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
380c0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
380d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
380e0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
380f0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
38100 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
38110 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
38120 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
38130 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
38140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38150 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
38160 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
38170 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
38180 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
38190 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
381a0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
381b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
381c0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
381d0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
381e0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
381f0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
38200 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
38210 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
38220 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
38230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38250 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
38260 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38270 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
38280 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
38290 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
382a0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
382b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
382c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
382d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
382e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
382f0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
38300 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
38310 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
38320 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
38330 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
38340 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
38350 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
38360 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
38370 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38390 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
383a0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
383b0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
383c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
383d0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
383e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
383f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
38400 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
38410 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
38420 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
38430 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
38440 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
38450 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
38460 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
38470 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
38480 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
38490 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
384a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
384b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
384c0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
384d0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
384e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
384f0 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
38500 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
38510 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
38520 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
38530 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
38540 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
38550 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
38560 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
38570 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
38580 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
38590 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
385a0 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
385b0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
385c0 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
385d0 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
385e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
385f0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
38600 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
38610 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
38620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
38630 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
38640 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
38650 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
38660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
38670 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
38680 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
38690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
386a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
386b0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
386c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
386d0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
386e0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
386f0 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
38700 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
38710 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
38720 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
38730 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
38740 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
38750 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
38760 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
38770 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
38780 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
38790 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
387a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
387b0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
387c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
387d0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
387e0 6e 65 20 53 51 4c 4