/ Hex Artifact Content
Login

Artifact 235e942dd8c01b414c2996828b4d0d2500faf8850f8b24ae17d31c172f519e69:


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 6e 6f 6e  an integer - non
19500 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero 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 2e 20  to enable them. 
19550 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19560 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19570 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
19580 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
19590 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
195a0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
195b0 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
195c0 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
195d0 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
195e0 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
195f0 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19600 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19610 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  /dd>.** <dt>SQLI
19620 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19630 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20  LE_QPSG</dt>.** 
19640 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
19650 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19660 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74  _QPSG option act
19670 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
19680 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75  vates.** the [qu
19690 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62  ery planner stab
196a0 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d  ility guarantee]
196b0 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74   (QPSG).  When t
196c0 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76  he QPSG is activ
196d0 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53  e,.** a single S
196e0 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65  QL query stateme
196f0 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  nt will always u
19700 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  se the same algo
19710 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73  rithm regardless
19720 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66  .** of values of
19730 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
19740 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20  rs].)^ The QPSG 
19750 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75  disables some qu
19760 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ery optimization
19770 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61  s.** that look a
19780 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20  t the values of 
19790 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
197a0 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
197b0 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a   some queries.**
197c0 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68   slower.  But th
197d0 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61  e QPSG has the a
197e0 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65  dvantage of more
197f0 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68   predictable beh
19800 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20  avior.  With.** 
19810 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c  the QPSG active,
19820 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
19830 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19840 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74   query plan in t
19850 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77  he field as.** w
19860 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  as used during t
19870 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61  esting in the la
19880 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c  b..** </dd>.** <
19890 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
198a0 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f  IG_TRIGGER_EQP</
198b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64  dt>.** <dd> By d
198c0 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70  efault, the outp
198d0 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55  ut of EXPLAIN QU
198e0 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64  ERY PLAN command
198f0 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69  s does not .** i
19900 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f  nclude output fo
19910 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73  r any operations
19920 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72   performed by tr
19930 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
19940 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  This.** option i
19950 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
19960 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61   clear (the defa
19970 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74  ult) a flag that
19980 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a   governs this.**
19990 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66   behavior. The f
199a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
199b0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
199c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e  eration is an in
199d0 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f 6e 2d 7a  teger -.** non-z
199e0 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75  ero to enable ou
199f0 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72  tput for trigger
19a00 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65   programs, or ze
19a10 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74  ro to disable it
19a20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19a30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19a40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19a50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20  eger into which 
19a60 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30  is written .** 0
19a70 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19a80 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74  e whether output
19a90 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61  -for-triggers ha
19aa0 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  s been disabled 
19ab0 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73  - 0 if .** it is
19ac0 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19ad0 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20   if it is.  .** 
19ae0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
19af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b00 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
19b10 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
19b20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
19b30 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
19b40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
19b50 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
19b60 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
19b70 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
19b80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19b90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
19ba0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
19bb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19bd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19be0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
19bf0 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
19c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19c10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19c20 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
19c30 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
19c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c60 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
19c70 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
19c80 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19c90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
19ca0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
19cb0 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
19cc0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19cd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19ce0 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
19cf0 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
19d00 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19d10 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19d20 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20  G_TRIGGER_EQP   
19d30 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20          1008 /* 
19d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19d60 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20  FIG_MAX         
19d70 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
19d80 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46  * Largest DBCONF
19d90 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  IG */../*.** CAP
19da0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
19db0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
19dc0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
19dd0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19de0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
19df0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19e00 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
19e10 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
19e20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
19e30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
19e40 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
19e50 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
19e60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
19e70 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
19e80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
19e90 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
19ea0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
19eb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
19ec0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19ed0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
19ee0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
19ef0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
19f00 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
19f10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19f20 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
19f30 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
19f40 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
19f50 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
19f60 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
19f70 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
19f80 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
19f90 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
19fa0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
19fb0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
19fc0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
19fd0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
19fe0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
19ff0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1a000 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1a010 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1a020 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1a030 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1a040 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1a050 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1a060 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1a070 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1a080 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1a090 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1a0a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1a0b0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1a0c0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1a0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
1a0e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1a0f0 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61  ) interface usua
1a100 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1a110 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68  [rowid] of.** th
1a120 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
1a130 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1a140 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
1a150 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
1a160 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
1a170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a180 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e  n D. ^Inserts in
1a190 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
1a1a0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
1a1b0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e  t.** recorded. ^
1a1c0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
1a1d0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
1a1e0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76  rowid tables hav
1a1f0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
1a200 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62  .** on the datab
1a210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1a220 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  , then sqlite3_l
1a230 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a240 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  (D) returns .** 
1a250 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  zero..**.** As w
1a260 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74  ell as being set
1a270 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
1a280 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72  s rows are inser
1a290 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73  ted into databas
1a2a0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65  e.** tables, the
1a2b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a2c0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1a2d0 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c   may be set expl
1a2e0 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71  icitly by.** [sq
1a2f0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1a300 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a310 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61  *.** Some virtua
1a320 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1a330 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45  tations may INSE
1a340 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77  RT rows into row
1a350 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20  id tables as.** 
1a360 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69  part of committi
1a370 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
1a380 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20   (e.g. to flush 
1a390 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64  data accumulated
1a3a0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f   in memory.** to
1a3b0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20   disk). In this 
1a3c0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  case subsequent 
1a3d0 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75  calls to this fu
1a3e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68  nction return th
1a3f0 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63  e rowid.** assoc
1a400 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65  iated with these
1a410 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54   internal INSERT
1a420 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69   operations, whi
1a430 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20  ch leads to .** 
1a440 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75  unintuitive resu
1a450 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62  lts. Virtual tab
1a460 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1a470 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65  ns that do write
1a480 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62   to rowid.** tab
1a490 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20  les in this way 
1a4a0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70  can avoid this p
1a4b0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72  roblem by restor
1a4c0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1a4d0 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65   .** rowid value
1a4e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a4f0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1a500 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20  rowid()] before 
1a510 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f  returning .** co
1a520 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65  ntrol to the use
1a530 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  r..**.** ^(If an
1a540 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
1a550 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1a560 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  r then this rout
1a570 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74  ine will .** ret
1a580 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
1a590 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20  of the inserted 
1a5a0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
1a5b0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a  he trigger is .*
1a5c0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20  * running. Once 
1a5d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1a5e0 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61  ram ends, the va
1a5f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
1a600 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
1a610 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
1a620 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
1a630 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66  he trigger was f
1a640 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  ired.)^.**.** ^A
1a650 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
1a660 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
1a670 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1a680 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
1a690 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1a6a0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
1a6b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1a6c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1a6d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
1a6e0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
1a6f0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
1a700 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
1a710 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
1a720 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
1a730 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
1a740 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
1a750 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
1a760 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
1a770 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
1a780 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
1a790 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
1a7a0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
1a7b0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1a7c0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
1a7d0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
1a7e0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
1a7f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
1a800 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
1a810 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
1a820 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
1a830 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
1a840 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
1a850 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
1a860 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
1a870 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
1a880 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
1a890 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
1a8a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
1a8b0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
1a8c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
1a8d0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
1a8e0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
1a8f0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
1a900 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
1a910 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1a920 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
1a930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
1a940 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
1a950 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
1a960 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a970 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a980 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
1a990 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
1a9a0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
1a9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a9c0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
1a9d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1a9e0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
1a9f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1aa00 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
1aa10 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
1aa20 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
1aa30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1aa40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1aa50 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1aa60 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
1aa70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
1aa80 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
1aa90 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
1aaa0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
1aab0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
1aac0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1aad0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
1aae0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1aaf0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1ab00 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20  PI3REF: Set the 
1ab10 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1ab20 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48  d value..** METH
1ab30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ab40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65  * The sqlite3_se
1ab50 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1ab60 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64  wid(D, R) method
1ab70 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c   allows the appl
1ab80 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65  ication to.** se
1ab90 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1aba0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  rned by calling 
1abb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1abc0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20  ert_rowid(D) to 
1abd0 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e  R .** without in
1abe0 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e  serting a row in
1abf0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
1ac00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ac10 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1ac20 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c  _rowid(sqlite3*,
1ac30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
1ac40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ac50 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
1ac60 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1ac70 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1ac80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1ac90 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1aca0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1acb0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
1acc0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
1acd0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
1ace0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
1acf0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
1ad00 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
1ad10 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
1ad20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ad30 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
1ad40 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
1ad50 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
1ad60 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1ad70 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1ad80 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
1ad90 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
1ada0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
1adb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
1adc0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
1add0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
1ade0 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
1adf0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1ae00 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
1ae10 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
1ae20 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
1ae30 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
1ae40 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1ae50 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
1ae60 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1ae70 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
1ae80 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1ae90 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
1aea0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
1aeb0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1aec0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1aed0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
1aee0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
1aef0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1af00 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
1af10 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
1af20 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
1af30 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1af40 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
1af50 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
1af60 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
1af70 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
1af80 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
1af90 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
1afa0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
1afb0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
1afc0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
1afd0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
1afe0 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
1aff0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
1b000 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1b010 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
1b020 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
1b030 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
1b040 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
1b050 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
1b060 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
1b070 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1b080 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
1b090 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
1b0a0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1b0b0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
1b0c0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
1b0d0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
1b0e0 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
1b0f0 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
1b100 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
1b110 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
1b120 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b130 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
1b140 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1b150 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
1b160 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
1b170 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
1b180 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
1b190 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
1b1a0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
1b1b0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
1b1c0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
1b1d0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1b1e0 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
1b1f0 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
1b200 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
1b210 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
1b220 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1b230 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
1b250 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
1b260 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
1b270 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
1b280 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
1b290 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
1b2a0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
1b2b0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
1b2c0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
1b2d0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1b2e0 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
1b2f0 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
1b300 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
1b310 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
1b320 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
1b330 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
1b340 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
1b350 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b360 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
1b370 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
1b380 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
1b390 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1b3a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1b3b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
1b3c0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
1b3d0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
1b3e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
1b3f0 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
1b400 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
1b410 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
1b420 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
1b430 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
1b440 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1b450 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
1b460 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
1b470 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
1b480 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b490 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
1b4a0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
1b4b0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
1b4c0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1b4d0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
1b4e0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
1b4f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b500 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1b510 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1b520 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1b530 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1b540 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
1b550 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b560 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b570 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b580 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b590 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b5a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b5b0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b5c0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
1b5d0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1b5e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1b5f0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
1b600 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1b610 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
1b620 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1b630 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1b640 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1b650 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1b660 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1b670 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b680 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b690 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1b6a0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1b6b0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1b6c0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1b6d0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1b6e0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1b6f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1b700 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1b710 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1b720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1b730 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1b740 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1b750 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1b760 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1b770 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1b780 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1b790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1b7a0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1b7b0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1b7c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b7d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1b7e0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1b7f0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1b800 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1b810 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1b820 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1b830 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1b840 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1b850 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1b860 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1b870 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1b880 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1b890 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1b8a0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1b8b0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1b8c0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1b8d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b8f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b900 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b910 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b920 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1b930 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b940 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b950 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b960 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b970 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b990 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b9a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b9b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b9c0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1b9d0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1b9e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b9f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1ba00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
1ba10 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
1ba20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ba30 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
1ba40 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
1ba50 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
1ba60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1ba70 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
1ba80 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
1ba90 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1baa0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
1bab0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
1bac0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
1bad0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
1bae0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
1baf0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
1bb00 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
1bb10 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
1bb20 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
1bb30 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
1bb40 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
1bb50 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
1bb60 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
1bb70 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
1bb80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
1bb90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1bba0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
1bbb0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
1bbc0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
1bbd0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
1bbe0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
1bbf0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
1bc00 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
1bc10 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
1bc20 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1bc30 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
1bc40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bc50 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
1bc60 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
1bc70 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
1bc80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
1bc90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
1bca0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
1bcb0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
1bcc0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
1bcd0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
1bce0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bcf0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
1bd00 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
1bd10 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
1bd20 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
1bd30 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
1bd40 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
1bd50 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
1bd60 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
1bd70 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
1bd80 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
1bd90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1bda0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
1bdb0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
1bdc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1bdd0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1bde0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
1bdf0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
1be00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1be10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
1be20 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
1be30 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
1be40 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
1be50 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
1be60 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1be70 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
1be80 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
1be90 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
1bea0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1beb0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
1bec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1bed0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
1bee0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
1bef0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1bf00 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1bf10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1bf20 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
1bf30 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
1bf40 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1bf50 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
1bf60 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
1bf70 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
1bf80 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
1bf90 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
1bfa0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1bfb0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
1bfc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bfd0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bfe0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
1bff0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
1c000 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1c010 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
1c020 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
1c030 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
1c040 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
1c050 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1c060 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
1c070 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
1c080 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1c090 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
1c0a0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
1c0b0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
1c0c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1c0d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1c0e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1c0f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
1c100 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  turns..*/.void s
1c110 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c120 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1c130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1c140 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1c150 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1c160 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1c170 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1c180 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1c190 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1c1a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1c1b0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1c1c0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1c1d0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1c1e0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c1f0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1c200 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1c210 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1c220 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1c230 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1c240 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1c250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c260 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1c270 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1c280 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1c290 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c2a0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1c2b0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1c2c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1c2d0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1c2e0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1c2f0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1c300 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1c310 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1c320 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1c330 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1c340 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1c350 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1c360 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1c370 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1c380 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1c390 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1c3a0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1c3b0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1c3c0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1c3d0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1c3e0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1c3f0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1c400 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1c410 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1c420 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1c430 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1c440 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1c450 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1c460 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1c470 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c480 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1c490 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1c4a0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1c4b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1c4c0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1c4d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1c4e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c4f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c500 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1c510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c520 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1c530 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1c540 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1c550 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1c560 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1c570 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1c580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1c590 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1c5a0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1c5b0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1c5c0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1c5d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1c5e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c5f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1c600 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c610 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1c620 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1c630 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1c640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1c650 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1c660 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1c670 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1c680 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1c690 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1c6a0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1c6b0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1c6c0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1c6d0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1c6e0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c6f0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c700 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1c710 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c720 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c730 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1c740 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c750 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1c760 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1c770 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
1c780 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1c790 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
1c7a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1c7b0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1c7c0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1c7d0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1c7e0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1c7f0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1c800 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1c810 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1c820 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1c830 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1c840 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c860 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c870 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1c880 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1c890 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1c8a0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1c8b0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1c8c0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1c8d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1c8e0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1c8f0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1c900 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1c910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c920 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1c930 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1c940 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1c950 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1c960 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c970 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1c980 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1c990 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1c9a0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1c9b0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1c9c0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c9d0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1c9e0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1c9f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1ca00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1ca10 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1ca20 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1ca30 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1ca40 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1ca50 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1ca60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1ca70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1ca80 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1ca90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1caa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1cab0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1cac0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1cad0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1cae0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1caf0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1cb00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1cb10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1cb20 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1cb30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1cb40 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1cb50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1cb60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1cb70 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1cb80 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1cb90 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1cba0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1cbb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1cbc0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1cbd0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1cbe0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1cbf0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1cc00 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1cc10 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1cc20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1cc30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1cc40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1cc50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1cc60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1cc70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1cc80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1cc90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1cca0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1ccb0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1ccc0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1ccd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1cce0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1ccf0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1cd00 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1cd10 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1cd20 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1cd30 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1cd40 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1cd50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1cd60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1cd70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1cd80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1cd90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1cda0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1cdb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1cdc0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1cdd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1cde0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1cdf0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1ce00 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1ce10 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1ce20 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1ce30 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1ce40 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1ce50 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1ce60 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1ce70 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1ce80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1ce90 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1cea0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1ceb0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1cec0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1ced0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1cee0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1cef0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1cf00 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1cf10 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1cf20 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1cf30 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1cf40 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1cf50 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1cf60 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1cf70 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1cf80 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1cf90 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1cfa0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1cfb0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1cfc0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1cfd0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1cfe0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1cff0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1d000 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1d010 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1d020 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1d030 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1d040 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1d050 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1d060 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1d070 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1d090 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1d0a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1d0b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1d0c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1d0d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1d0e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d100 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1d110 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1d120 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1d130 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1d140 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1d150 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1d160 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1d170 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1d180 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1d190 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1d1a0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1d1b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1d1c0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1d1d0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1d1e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1d1f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1d200 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1d210 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1d220 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1d230 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1d240 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1d250 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1d260 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1d270 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1d280 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1d290 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1d2a0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1d2b0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1d2c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1d2d0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1d2e0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1d2f0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1d300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d310 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1d320 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1d330 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d340 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1d350 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1d360 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1d370 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1d380 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1d390 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1d3a0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1d3b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1d3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1d3d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1d3e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d3f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1d400 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1d410 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1d420 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1d430 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1d440 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1d450 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1d460 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1d470 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1d480 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1d490 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1d4a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1d4b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1d4c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1d4d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1d4e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1d4f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1d500 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1d510 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1d520 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1d530 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1d540 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1d550 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1d560 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1d570 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1d580 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1d590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1d5a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1d5b0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1d5c0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1d5d0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1d5e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d5f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1d600 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1d610 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1d620 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1d630 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1d640 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d650 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1d660 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1d670 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1d680 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1d690 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1d6a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d6b0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1d6c0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1d6d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1d6e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1d6f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1d700 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1d710 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1d720 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1d730 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d740 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1d750 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1d760 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1d770 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1d780 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d790 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1d7a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1d7b0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1d7c0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1d7d0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1d7e0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1d7f0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1d800 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1d810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1d820 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1d830 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1d840 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1d850 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1d860 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1d870 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1d880 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1d890 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1d8a0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1d8b0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1d8c0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1d8d0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1d8e0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1d8f0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1d900 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1d910 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1d920 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1d930 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1d940 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1d950 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1d960 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1d970 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1d980 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1d990 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1d9a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1d9b0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1d9c0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1d9d0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1d9e0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1d9f0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1da00 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1da10 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1da20 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1da30 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1da40 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1da50 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1da60 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1da70 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1da80 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1da90 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1daa0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1dab0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1dac0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1dad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1dae0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1daf0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1db00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1db10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1db20 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1db30 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1db40 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1db50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1db60 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1db70 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1db80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1db90 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1dba0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1dbb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1dbc0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1dbd0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1dbe0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1dbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1dc00 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1dc10 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1dc20 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1dc30 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1dc40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1dc50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1dc60 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1dc70 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1dc80 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1dc90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dca0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1dcb0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1dcc0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1dcd0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1dce0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1dcf0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1dd00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1dd10 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1dd20 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1dd30 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1dd40 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1dd50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1dd60 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1dd70 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1dd80 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1dd90 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1dda0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1ddb0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1ddc0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1ddd0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1dde0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1ddf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1de00 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1de10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1de20 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1de30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1de40 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1de50 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1de60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1de70 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1de80 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1de90 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1dea0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1deb0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1dec0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ded0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1dee0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1def0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1df00 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1df10 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1df20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1df30 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1df40 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1df50 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1df60 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1df70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1df80 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1df90 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1dfa0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1dfb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1dfc0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1dfd0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1dfe0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1dff0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1e000 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1e010 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1e020 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1e030 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1e040 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1e050 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1e060 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1e070 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1e080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1e090 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1e0a0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1e0b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1e0c0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1e0d0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1e0e0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1e0f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1e100 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1e110 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e120 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1e130 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1e140 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1e150 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e160 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1e170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1e180 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1e190 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1e1a0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1e1b0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1e1c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1e1d0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1e1e0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1e1f0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1e200 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1e210 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1e220 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1e230 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1e240 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1e250 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1e260 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1e270 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1e280 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1e290 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1e2a0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1e2b0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1e2c0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1e2d0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1e2e0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1e2f0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1e300 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1e310 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1e320 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1e330 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1e340 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1e350 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1e360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1e370 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1e380 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e390 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1e3a0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1e3b0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1e3c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1e3d0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1e3e0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1e3f0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1e400 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1e410 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1e420 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1e430 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1e440 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1e450 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1e460 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1e470 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1e480 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1e490 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1e4a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1e4b0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1e4c0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1e4d0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1e4e0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1e4f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1e500 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1e510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1e520 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1e530 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1e540 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1e550 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1e560 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1e570 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1e580 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1e590 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1e5a0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1e5b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1e5c0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1e5d0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72  f the common for
1e5e0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1e5f0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1e600 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69  dard library pri
1e610 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73  ntf() .** plus s
1e620 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1e630 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1e640 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c  ats ([%q], [%Q],
1e650 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29   [%w], and [%z])
1e660 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75  ..** See the [bu
1e670 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d  ilt-in printf()]
1e680 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
1e690 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a  or details..**.*
1e6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e6b0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1e6c0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1e6d0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1e6e0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1e6f0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1e700 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1e710 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a  e3_malloc64()]..
1e720 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e730 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e740 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e750 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e760 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e770 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e780 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e790 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e7a0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e7b0 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61  lloc64()] is una
1e7c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1e7d0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1e7e0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1e7f0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1e800 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1e810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1e820 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1e830 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1e840 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1e850 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1e860 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1e870 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1e880 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1e890 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1e8a0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1e8b0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1e8c0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1e8d0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1e8e0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1e8f0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1e900 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1e910 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1e920 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1e930 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1e940 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1e950 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1e960 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1e970 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1e980 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1e990 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1e9a0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1e9b0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1e9c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1e9d0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1e9e0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1e9f0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1ea00 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1ea10 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1ea20 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1ea30 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1ea40 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1ea50 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1ea60 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1ea70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1ea80 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1ea90 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1eaa0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1eab0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1eac0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1ead0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1eae0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1eaf0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1eb00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1eb10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1eb20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1eb30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1eb40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1eb50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1eb60 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1eb70 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1eb80 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1eb90 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1eba0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1ebb0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1ebc0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1ebd0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1ebe0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1ebf0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1ec00 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1ec10 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1ec20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1ec30 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1ec40 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1ec50 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1ec60 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1ec70 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tf()..**.** See 
1ec80 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e  also:  [built-in
1ec90 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69   printf()], [pri
1eca0 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ntf() SQL functi
1ecb0 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  on].*/.char *sql
1ecc0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1ecd0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1ece0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1ecf0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1ed00 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1ed10 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1ed20 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1ed30 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1ed40 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1ed50 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1ed60 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1ed70 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1ed80 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1ed90 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1eda0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1edb0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1edc0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1edd0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1ede0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1edf0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1ee00 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1ee10 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1ee20 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1ee30 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1ee40 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1ee50 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1ee60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1ee70 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1ee80 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1ee90 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1eea0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1eeb0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1eec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1eed0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1eee0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1eef0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1ef00 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1ef10 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1ef20 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1ef30 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1ef40 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1ef50 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1ef60 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1ef70 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1ef80 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1ef90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1efa0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1efb0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1efc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1efd0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1efe0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1eff0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1f000 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f020 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1f030 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1f040 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1f050 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1f060 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1f070 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1f080 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1f090 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1f0a0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1f0b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1f0c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1f0d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1f0e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1f0f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1f100 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f110 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1f120 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1f130 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1f140 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1f150 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1f160 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1f170 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1f180 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1f190 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1f1a0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1f1b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1f1c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1f1d0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1f1e0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1f1f0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1f200 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1f210 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1f220 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1f230 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1f240 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1f250 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1f260 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1f270 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1f280 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1f290 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1f2a0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1f2b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1f2c0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1f2d0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1f2e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1f2f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1f300 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1f310 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1f320 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1f330 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1f340 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1f350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1f360 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1f370 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1f380 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1f390 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1f3a0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1f3b0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1f3c0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1f3d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f3e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1f3f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1f400 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1f410 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1f420 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1f430 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1f440 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1f450 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f460 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f470 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1f480 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1f490 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1f4a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1f4b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1f4c0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1f4d0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1f4e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1f4f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1f500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1f510 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1f520 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1f530 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1f540 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1f550 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1f560 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1f570 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1f580 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1f590 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1f5a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1f5b0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1f5c0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1f5d0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1f5e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1f5f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f600 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1f610 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1f620 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1f630 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f640 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1f650 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1f660 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1f670 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1f680 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1f690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f6a0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1f6b0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1f6c0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1f6d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f6e0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1f6f0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1f700 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1f710 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1f720 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1f730 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1f740 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1f750 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1f760 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1f770 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1f780 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1f790 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1f7a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1f7b0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1f7c0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1f7d0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f7e0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1f7f0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1f800 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1f810 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1f820 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1f830 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f840 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1f850 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1f860 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1f870 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1f880 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1f890 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1f8a0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1f8b0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1f8c0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1f8d0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1f8e0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1f8f0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1f900 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1f910 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1f920 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1f930 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1f940 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f950 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1f960 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1f970 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1f980 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1f990 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1f9a0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1f9b0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1f9c0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1f9d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1f9e0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1f9f0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1fa00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1fa10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1fa20 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1fa30 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1fa40 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1fa50 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1fa60 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1fa70 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1fa80 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1fa90 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1faa0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1fab0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1fac0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1fad0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1fae0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1faf0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1fb00 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1fb10 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1fb20 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1fb30 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1fb40 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1fb50 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1fb60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1fb70 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1fb80 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1fb90 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1fba0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1fbb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1fbc0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1fbd0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1fbe0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1fbf0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1fc00 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1fc10 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1fc20 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1fc30 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1fc40 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1fc50 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1fc60 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1fc70 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1fc80 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1fc90 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1fca0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1fcb0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1fcc0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1fcd0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1fce0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1fcf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1fd00 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1fd10 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1fd20 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1fd30 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1fd40 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1fd50 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1fd60 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1fd70 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1fd80 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1fd90 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1fda0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fdb0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1fdc0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1fdd0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1fde0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1fdf0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1fe00 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1fe10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1fe20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1fe30 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1fe40 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1fe50 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1fe60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1fe70 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1fe80 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1fe90 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1fea0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1feb0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1fec0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1fed0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1fee0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fef0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1ff00 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1ff10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1ff20 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1ff30 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1ff40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1ff50 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1ff60 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1ff70 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1ff80 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1ff90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1ffa0 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1ffb0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1ffc0 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1ffd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1ffe0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1fff0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
20000 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
20010 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
20020 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
20030 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
20040 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
20050 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
20060 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
20070 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
20080 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
20090 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
200a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
200b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
200c0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
200d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
200e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
200f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
20100 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
20110 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
20120 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
20130 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
20140 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
20150 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
20160 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
20170 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20180 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20190 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
201a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
201b0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
201c0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
201d0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
201e0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
201f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
20200 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20210 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
20220 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20230 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
20240 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
20250 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
20260 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
20270 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
20280 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
20290 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
202a0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
202b0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
202c0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
202d0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
202e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
202f0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
20300 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
20310 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
20320 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
20330 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
20340 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20350 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
20360 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
20370 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20380 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20390 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
203a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
203b0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
203c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
203d0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
203e0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
203f0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
20400 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
20410 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
20420 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
20430 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
20440 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20450 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
20460 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
20470 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
20480 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
20490 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
204a0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
204b0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
204c0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
204d0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
204e0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
204f0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
20500 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
20510 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
20520 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
20530 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
20540 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
20550 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
20560 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
20570 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
20580 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
20590 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
205a0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
205b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
205c0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
205d0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
205e0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
205f0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
20600 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
20610 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
20620 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
20630 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
20640 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
20650 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
20660 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
20670 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
20680 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
20690 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
206a0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
206b0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
206c0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
206d0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
206e0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
206f0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
20700 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
20710 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
20720 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
20730 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
20740 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
20750 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
20760 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
20770 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
20780 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
20790 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
207a0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
207b0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
207c0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
207d0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
207e0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
207f0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
20800 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
20810 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
20820 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
20830 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
20840 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
20850 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20860 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20880 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
20890 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
208a0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
208b0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57   sqlite3.** KEYW
208c0 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65  ORDS: {authorize
208d0 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a  r callback}.**.*
208e0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
208f0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
20900 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20910 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
20920 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
20930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
20940 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
20950 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
20960 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
20970 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20980 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
20990 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
209a0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
209b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
209c0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
209d0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
209e0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
209f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20a00 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
20a10 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71  repare16()], [sq
20a20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20a30 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  v2()],.** and [s
20a40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20a50 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v3()].  ^At var
20a60 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
20a70 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
20a80 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
20a90 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
20aa0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
20ab0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
20ac0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
20ad0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20ae0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
20af0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
20b00 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
20b10 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
20b20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
20b30 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
20b40 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
20b50 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
20b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
20b70 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
20b80 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
20b90 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
20ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
20bb0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
20bc0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
20bd0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
20be0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
20bf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20c00 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
20c10 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
20c20 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
20c30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
20c40 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
20c50 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
20c60 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
20c70 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
20c80 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
20c90 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
20ca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20cb0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
20cc0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
20cd0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
20ce0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
20cf0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
20d00 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
20d10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20d20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
20d30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
20d40 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
20d50 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
20d60 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
20d70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
20d80 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
20d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20da0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
20db0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
20dc0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
20dd0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
20de0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
20df0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
20e00 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
20e10 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
20e20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
20e30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
20e40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20e50 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
20e60 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
20e70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
20e80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
20e90 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
20ea0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
20eb0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
20ec0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20ed0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
20ee0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
20ef0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
20f00 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
20f10 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
20f20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20f30 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
20f40 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
20f50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
20f60 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65  e callback are e
20f70 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  ither NULL point
20f80 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d  ers or zero-term
20f90 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a  inated strings.*
20fa0 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  * that contain a
20fb0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
20fc0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
20fd0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
20fe0 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  zed..** Applicat
20ff0 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73  ions must always
21000 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20   be prepared to 
21010 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c  encounter a NULL
21020 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a   pointer in any.
21030 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  ** of the third 
21040 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74  through the sixt
21050 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  h parameters of 
21060 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
21070 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
21080 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21090 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
210a0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
210b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
210c0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
210d0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
210e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
210f0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
21100 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
21110 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
21120 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
21130 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
21140 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
21150 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
21160 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
21170 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
21180 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
21190 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
211a0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
211b0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
211c0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
211d0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
211e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
211f0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e   table..** ^When
21200 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65   a table is refe
21210 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c  renced by a [SEL
21220 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75  ECT] but no colu
21230 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a  mn values are.**
21240 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
21250 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20  that table (for 
21260 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65  example in a que
21270 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45  ry like.** "SELE
21280 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d  CT count(*) FROM
21290 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20   tab") then the 
212a0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75  [SQLITE_READ] au
212b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
212c0 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  k.** is invoked 
212d0 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61  once for that ta
212e0 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d  ble with a colum
212f0 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61  n name that is a
21300 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
21310 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21320 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21330 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
21340 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
21350 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
21360 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
21370 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
21380 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
21390 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
213a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
213b0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
213c0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
213d0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
213e0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
213f0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
21400 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
21410 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
21420 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
21430 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
21440 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
21450 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
21460 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21470 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
21480 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
21490 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
214a0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
214b0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
214c0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
214d0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
214e0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
214f0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
21500 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
21510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
21520 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
21530 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
21540 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
21550 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
21560 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
21570 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
21580 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
21590 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
215a0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
215b0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
215c0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
215d0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
215e0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
215f0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
21600 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
21610 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
21620 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
21630 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21640 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
21650 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
21660 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
21670 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
21680 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
21690 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
216a0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
216b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
216c0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
216d0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
216e0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
216f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
21700 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
21710 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
21720 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
21730 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21740 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
21750 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
21760 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
21770 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
21780 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
21790 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
217a0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
217b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
217c0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
217d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
217e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
217f0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
21800 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
21810 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
21820 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
21830 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
21840 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
21850 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
21860 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
21870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
21880 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21890 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
218a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
218b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
218c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
218d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
218e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
218f0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
21900 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21910 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21930 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21940 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21950 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
21960 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
21970 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
21980 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
21990 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
219a0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
219b0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
219c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
219d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
219e0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
219f0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
21a00 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
21a10 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
21a20 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
21a30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
21a40 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
21a50 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
21a60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21a70 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
21a80 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
21a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
21ab0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
21ac0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
21ad0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
21ae0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
21af0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
21b00 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
21b10 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
21b20 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
21b30 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
21b40 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
21b50 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
21b60 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
21b70 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
21b80 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
21b90 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
21ba0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
21bb0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
21bc0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
21bd0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
21be0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
21bf0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
21c00 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
21c10 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
21c20 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
21c30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21c40 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
21c50 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
21c60 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
21c70 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
21c80 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
21c90 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
21ca0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21cb0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21cc0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
21cd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21ce0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
21cf0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
21d00 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
21d10 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
21d20 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
21d30 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
21d40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
21d50 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
21d60 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
21d70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
21d80 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
21d90 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
21da0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
21db0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
21dc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
21dd0 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
21de0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
21df0 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
21e00 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
21e10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
21e20 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
21e30 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
21e40 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
21e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e60 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
21e70 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
21e80 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
21e90 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
21ea0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
21eb0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
21ec0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
21ed0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
21ee0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
21ef0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
21f00 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
21f10 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21f20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21f30 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
21f40 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
21f50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
21f60 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
21f70 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
21f80 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
21f90 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
21fa0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
21fb0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
21fc0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
21fd0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
21fe0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
21ff0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
22000 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
22010 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
22020 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
22030 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
22040 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
22050 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
22060 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
22070 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
22080 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
22090 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
220a0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
220b0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
220c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
220d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
220e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
220f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
22100 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
22110 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
22120 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
22130 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
22140 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
22150 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
22160 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
22170 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
22180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22190 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
221a0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
221b0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
221c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
221d0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
221e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
221f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22200 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
22210 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
22220 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
22230 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
22240 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
22250 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
22260 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
22270 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
22280 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
22290 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
222a0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
222b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
222c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
222d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
222e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
222f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
22300 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22310 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
22320 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
22330 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22340 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22350 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22360 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22370 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
22380 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22390 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
223a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
223b0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
223c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
223d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
223e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
223f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22400 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
22410 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22420 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22430 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22440 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22450 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
22460 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22470 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22480 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22490 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
224a0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
224b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
224c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
224d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
224e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
224f0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
22500 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22510 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22520 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22530 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
22540 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
22550 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22560 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22570 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22580 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
22590 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
225a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
225b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
225c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
225d0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
225e0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
225f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22610 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22620 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
22630 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
22640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22650 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22670 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
22680 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
22690 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
226a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
226b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
226c0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
226d0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
226e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
226f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22710 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
22720 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
22730 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22740 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22760 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
22770 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
22780 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22790 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
227a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
227b0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
227c0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
227d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
227e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
227f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22800 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
22810 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
22820 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22830 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22840 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
22850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22860 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22870 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22880 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22890 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
228a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
228b0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
228c0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
228d0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
228e0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
228f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
22900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22910 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
22920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22930 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
22940 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
22950 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22960 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22970 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22980 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
22990 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
229a0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
229b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
229c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
229d0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
229e0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
229f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22a00 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
22a10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22a20 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
22a30 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
22a40 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
22a50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22a70 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
22a80 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
22a90 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22aa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ac0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
22ad0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
22ae0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
22af0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22b10 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
22b20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
22b30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
22b40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22b60 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
22b70 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
22b80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22b90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22bb0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
22bc0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
22bd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22be0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22c00 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
22c10 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
22c20 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22c30 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
22c50 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
22c60 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
22c70 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
22c80 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
22c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
22ca0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
22cb0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
22cc0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
22cd0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
22ce0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
22cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22d00 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
22d10 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
22d20 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
22d30 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
22d40 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
22d50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22d60 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
22d70 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
22d80 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
22d90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
22da0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
22db0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22dc0 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  s are deprecated
22dd0 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
22de0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69  e3_trace_v2()] i
22df0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74  nterface.** inst
22e00 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69  ead of the routi
22e10 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65  nes described he
22e20 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  re..**.** These 
22e30 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
22e40 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
22e50 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
22e60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
22e70 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
22e80 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
22e90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
22ea0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
22eb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22ec0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
22ed0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
22ee0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
22ef0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
22f00 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
22f10 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
22f20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
22f30 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
22f40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22f50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22f60 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
22f70 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
22f80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22f90 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
22fa0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
22fb0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
22fc0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
22fd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
22fe0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
22ff0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
23000 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
23010 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
23020 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
23030 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
23040 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
23050 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
23060 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
23070 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
23080 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
23090 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
230a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
230b0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
230c0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
230d0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
230e0 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
230f0 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
23100 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
23110 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
23120 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
23130 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
23140 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
23150 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
23160 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
23170 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23180 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23190 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
231a0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
231b0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
231c0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
231d0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
231e0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
231f0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
23200 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
23210 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
23220 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
23230 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
23240 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
23250 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
23260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
23270 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
23280 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
23290 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
232a0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
232b0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
232c0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
232d0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
232e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
232f0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
23300 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
23310 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
23320 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
23330 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
23340 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
23360 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
23370 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
23380 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
23390 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
233a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
233b0 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
233c0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
233d0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
233e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63  ,.   void(*xTrac
233f0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23400 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
23410 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23420 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
23430 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
23440 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
23450 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
23460 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
23470 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
23480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23490 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
234a0 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
234b0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
234c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
234d0 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
234e0 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
234f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
23500 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
23510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
23520 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
23530 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61   logic.  The M a
23540 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
23550 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23560 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20  D,M,X,P)] is an 
23570 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
23580 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
23590 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
235a0 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
235b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
235c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
235d0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
235e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
235f0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23600 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
23610 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
23620 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
23630 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
23640 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23650 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
23660 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
23670 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23680 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23690 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
236a0 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
236b0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
236c0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
236d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
236e0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
236f0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
23700 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
23710 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
23720 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
23730 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
23740 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
23750 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
23760 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
23770 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
23780 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
23790 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
237a0 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
237b0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
237c0 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
237d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
237e0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
237f0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
23800 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
23810 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
23820 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
23830 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
23840 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
23850 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
23860 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
23870 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
23880 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
23890 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
238a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
238b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
238c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
238d0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
238e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
238f0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
23900 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
23910 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
23920 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
23930 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
23940 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
23950 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
23960 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
23970 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
23980 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
23990 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
239a0 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
239b0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
239c0 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
239d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
239e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
239f0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
23a00 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
23a10 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
23a20 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
23a30 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
23a40 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
23a50 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
23a60 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
23a70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23a80 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
23a90 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
23aa0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
23ab0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
23ac0 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
23ad0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
23ae0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
23af0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
23b00 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23b10 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
23b20 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23b30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23b40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23b50 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23b60 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
23b70 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
23b80 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
23b90 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
23ba0 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
23bb0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
23bc0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
23bd0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
23be0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
23bf0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
23c00 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
23c10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
23c20 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
23c30 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
23c40 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
23c50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23c60 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
23c70 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
23c80 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
23c90 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23ca0 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
23cb0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
23cc0 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
23cd0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
23ce0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23cf0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23d00 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
23d10 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23d20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
23d30 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
23d40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
23d50 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
23d60 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
23d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
23d80 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
23d90 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
23da0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
23db0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
23dc0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
23dd0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
23de0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
23df0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
23e00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
23e10 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
23e20 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
23e30 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
23e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23e50 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
23e60 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
23e70 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23e80 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
23e90 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
23ea0 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
23eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
23ec0 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
23ed0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
23ee0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
23ef0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
23f00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
23f10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23f20 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
23f30 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
23f40 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
23f50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
23f60 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
23f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
23f80 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
23f90 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
23fa0 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
23fb0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
23fc0 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
23fd0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
23fe0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
23ff0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
24000 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
24010 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
24020 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
24030 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
24040 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
24050 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
24060 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
24070 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
24080 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
24090 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
240a0 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
240b0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
240c0 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
240d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
240e0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
240f0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
24100 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
24110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24120 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
24130 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
24140 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
24150 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
24160 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
24170 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
24180 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
24190 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
241a0 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
241b0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
241c0 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
241d0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
241e0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
241f0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
24200 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
24210 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
24220 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
24230 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
24240 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
24250 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
24260 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
24270 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
24280 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
24290 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
242a0 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
242b0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
242c0 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
242d0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
242e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
242f0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
24300 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24310 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
24320 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
24330 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
24340 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
24350 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
24360 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
24370 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
24380 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
24390 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
243a0 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
243b0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
243c0 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
243d0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
243e0 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
243f0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
24400 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
24410 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
24420 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
24430 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
24440 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
24450 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
24460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
24470 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
24480 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
24490 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
244a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
244b0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
244c0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
244d0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
244e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
244f0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
24500 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
24510 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
24520 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
24530 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
24540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24550 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
24560 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
24570 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24580 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
24590 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
245a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
245b0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
245c0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
245d0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
245e0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
245f0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
24600 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
24610 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
24620 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
24630 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
24640 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
24650 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
24660 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
24670 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24680 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
24690 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
246a0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
246b0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
246c0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
246d0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
246e0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
246f0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
24700 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
24710 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
24720 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
24730 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
24740 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
24750 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
24760 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24770 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
24780 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
24790 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
247a0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
247b0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
247c0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
247d0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
247e0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
247f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24800 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
24810 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
24820 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
24830 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
24840 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
24850 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
24860 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
24870 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
24880 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
24890 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
248a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
248b0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
248c0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
248d0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
248e0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
248f0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
24900 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
24910 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
24920 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
24930 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
24940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
24950 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
24960 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24970 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
24980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24990 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
249a0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
249b0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
249c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
249d0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
249e0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
249f0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
24a00 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
24a10 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
24a20 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
24a30 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
24a40 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
24a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
24a60 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
24a70 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
24a80 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
24a90 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
24aa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
24ab0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
24ac0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
24ad0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
24ae0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
24af0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
24b00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
24b10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24b20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
24b30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
24b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b50 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
24b60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
24b70 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
24b80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24b90 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
24ba0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
24bb0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
24bc0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
24bd0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
24be0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
24bf0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
24c00 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
24c10 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
24c20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
24c30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
24c40 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
24c50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
24c60 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
24c70 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
24c80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
24c90 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
24ca0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
24cb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24cc0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
24cd0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
24ce0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
24cf0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
24d00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
24d10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
24d20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
24d30 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
24d40 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
24d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
24d60 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
24d70 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
24d80 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
24d90 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
24da0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
24db0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
24dc0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
24dd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
24de0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
24df0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
24e00 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
24e10 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
24e20 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
24e30 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
24e40 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
24e50 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
24e60 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
24e70 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
24e80 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
24e90 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
24ea0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
24eb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
24ec0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
24ed0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
24ee0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
24ef0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
24f00 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
24f10 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
24f20 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
24f30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
24f40 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
24f50 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
24f60 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
24f70 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
24f80 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
24f90 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
24fa0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
24fb0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
24fc0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
24fd0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
24fe0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
24ff0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
25000 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
25010 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
25020 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
25030 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
25040 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
25050 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
25060 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
25070 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
25080 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
25090 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
250a0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
250b0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
250c0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
250d0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
250e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
250f0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
25100 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25110 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
25120 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25130 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
25140 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
25150 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
25160 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25170 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
25180 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25190 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
251a0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
251b0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
251c0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
251d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
251e0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
251f0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
25200 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
25210 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25220 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
25230 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
25240 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
25250 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
25260 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
25270 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
25280 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
25290 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
252a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
252b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
252c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
252d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
252e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
252f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
25300 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
25310 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
25320 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25330 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
25340 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
25350 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
25360 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25370 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
25380 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
25390 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
253a0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
253b0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
253c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
253d0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
253e0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
253f0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25400 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
25410 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
25420 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
25430 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25440 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25450 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
25460 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
25470 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
25480 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
25490 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
254a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
254b0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
254c0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
254d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
254e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
254f0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
25500 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25510 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
25520 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25530 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
25540 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
25550 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
25560 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
25570 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
25580 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
25590 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
255a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
255b0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
255c0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
255d0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
255e0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
255f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25600 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
25610 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
25620 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25630 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
25640 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
25650 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
25660 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
25670 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
25680 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
25690 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
256a0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
256b0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
256c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
256d0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
256e0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
256f0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
25700 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25710 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
25720 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
25730 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
25740 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
25750 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
25760 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
25770 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
25780 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
25790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
257a0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
257b0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
257c0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
257d0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
257e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
257f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25800 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25810 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
25820 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
25830 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25840 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
25850 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25860 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
25870 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
25880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25890 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
258a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
258b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
258c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
258d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
258e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
258f0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
25900 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
25910 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
25920 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
25930 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
25940 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
25950 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
25960 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
25970 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
25980 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
25990 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
259a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
259b0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
259c0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
259d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
259e0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
259f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
25a00 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
25a10 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
25a20 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
25a30 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
25a40 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
25a50 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
25a60 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
25a70 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
25a80 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
25a90 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
25aa0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
25ab0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
25ac0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
25ad0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
25ae0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
25af0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
25b00 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
25b10 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
25b20 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
25b30 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
25b40 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
25b50 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
25b60 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
25b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
25b80 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
25b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25ba0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
25bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
25bc0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
25bd0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
25be0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
25bf0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
25c00 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
25c10 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
25c20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
25c30 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
25c40 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
25c50 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
25c60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
25c70 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
25c80 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
25c90 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
25ca0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
25cb0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
25cc0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
25cd0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
25ce0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
25cf0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25d00 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
25d10 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
25d20 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
25d30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
25d40 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
25d50 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
25d60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
25d70 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
25d80 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
25d90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
25da0 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c  tion..** URI fil
25db0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
25dc0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
25dd0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
25de0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
25df0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
25e00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
25e10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
25e20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
25e30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
25e40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
25e50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
25e60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
25e70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
25e80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
25e90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
25ea0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
25eb0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
25ec0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
25ed0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
25ee0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25ef0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
25f00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
25f10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
25f20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
25f30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
25f40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
25f50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25f60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
25f70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
25f80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25f90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
25fa0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
25fb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
25fc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
25fd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
25fe0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
25ff0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
26000 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
26010 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
26020 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
26030 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
26040 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
26050 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
26060 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
26070 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
26080 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
26090 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
260a0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
260b0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
260c0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
260d0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
260e0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
260f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
26100 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
26110 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
26120 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
26130 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
26140 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
26150 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
26160 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
26170 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
26180 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
26190 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
261a0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
261b0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
261c0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
261d0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
261e0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
261f0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
26200 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
26210 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
26220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
26230 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
26240 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
26250 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
26260 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
26270 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
26280 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
26290 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
262a0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
262b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
262c0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
262d0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
262e0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
262f0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
26300 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
26310 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
26320 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
26330 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
26340 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26350 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
26360 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
26370 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
26380 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
26390 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
263a0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
263b0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
263c0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
263d0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
263e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
263f0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26400 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
26410 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
26420 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
26430 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
26440 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
26450 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
26460 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
26470 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
26480 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26490 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
264a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
264b0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
264c0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
264d0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
264e0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
264f0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
26500 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
26510 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
26520 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
26530 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
26540 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
26550 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
26560 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
26570 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26580 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
26590 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
265a0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
265b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
265c0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
265d0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
265e0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
265f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
26600 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
26610 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
26620 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
26630 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
26640 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26650 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
26660 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
26670 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
26680 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
26690 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
266a0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
266b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
266c0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
266d0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
266e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
266f0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
26700 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26710 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
26720 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
26730 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
26740 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
26750 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
26760 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
26770 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
26780 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
26790 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
267a0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
267b0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
267c0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
267d0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
267e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
267f0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26800 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
26810 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
26820 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
26830 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
26840 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
26850 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26860 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
26870 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26880 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
26890 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
268a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
268b0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
268c0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
268d0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
268e0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
268f0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26900 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
26910 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26920 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
26930 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
26940 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
26950 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
26960 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
26970 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
26980 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
26990 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
269a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
269b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
269c0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
269d0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
269e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
269f0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
26a00 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
26a10 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
26a20 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
26a30 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
26a40 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
26a50 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
26a60 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
26a70 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
26a80 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
26a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26aa0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
26ab0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
26ac0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
26ad0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
26ae0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
26af0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
26b00 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
26b10 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
26b20 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
26b30 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
26b40 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
26b50 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
26b60 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
26b70 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
26b80 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
26b90 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
26ba0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26bb0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
26bc0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
26bd0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
26be0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
26bf0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
26c00 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
26c10 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
26c20 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
26c30 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
26c40 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
26c50 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
26c60 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
26c70 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
26c80 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
26c90 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
26ca0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
26cb0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
26cc0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
26cd0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
26ce0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
26cf0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
26d00 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
26d10 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
26d20 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
26d30 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
26d40 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
26d50 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
26d60 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
26d70 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
26d80 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
26d90 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
26da0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
26db0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
26dc0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
26dd0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
26de0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
26df0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
26e00 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
26e10 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
26e20 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
26e30 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
26e40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26e50 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
26e60 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
26e70 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
26e80 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
26e90 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
26ea0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
26eb0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
26ec0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
26ed0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
26ee0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
26ef0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
26f00 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
26f10 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
26f20 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
26f30 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
26f40 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
26f50 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
26f60 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
26f70 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
26f80 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
26f90 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
26fa0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
26fb0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26fc0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
26fd0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
26fe0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26ff0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
27000 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
27010 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
27020 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
27030 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
27040 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
27050 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
27060 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
27070 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
27080 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
27090 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
270a0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
270b0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
270c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
270d0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
270e0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
270f0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
27100 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
27110 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
27120 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
27130 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
27140 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
27150 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
27160 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
27170 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
27180 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
27190 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
271a0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
271b0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
271c0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
271d0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
271e0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
271f0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
27200 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27210 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
27220 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
27230 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
27240 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
27250 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
27260 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
27270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
27280 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
27290 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
272a0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
272b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
272c0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
272d0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
272e0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
272f0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
27300 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
27310 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
27320 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
27330 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
27340 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
27350 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
27360 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
27370 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
27380 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
27390 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
273a0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
273b0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
273c0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
273d0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
273e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
273f0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
27400 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
27410 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
27420 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27430 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
27440 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
27450 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
27460 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
27470 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
27480 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
27490 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
274a0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
274b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
274c0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
274d0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
274e0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
274f0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
27500 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
27510 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27520 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27530 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
27540 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
27550 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
27560 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27570 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
27580 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
27590 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
275a0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
275b0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
275c0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
275d0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
275e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
275f0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
27600 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27610 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
27620 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
27630 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
27640 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
27650 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
27660 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
27670 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
27680 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
27690 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
276a0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
276b0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
276c0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
276d0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
276e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
276f0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
27700 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
27710 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
27720 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
27730 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
27740 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
27750 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
27760 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
27770 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
27780 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
27790 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
277a0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
277b0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
277c0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
277d0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
277e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
277f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
27800 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
27810 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
27820 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
27830 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
27840 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
27850 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
27860 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
27870 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27880 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
27890 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
278a0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
278b0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
278c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
278d0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
278e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
278f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27900 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
27910 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
27920 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
27930 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
27940 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
27950 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
27960 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
27970 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
27980 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
27990 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
279a0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
279b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
279c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
279d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
279e0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
279f0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
27a00 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
27a10 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
27a20 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
27a30 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
27a40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
27a50 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
27a60 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
27a70 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
27a80 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
27a90 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
27aa0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
27ab0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27ac0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
27ad0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
27ae0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
27af0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
27b00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27b10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
27b20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
27b30 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
27b40 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
27b50 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
27b60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
27b70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
27b80 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
27b90 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
27ba0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
27bb0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
27bc0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
27bd0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
27be0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27bf0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
27c00 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
27c10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27c20 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
27c30 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
27c40 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
27c50 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
27c60 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
27c70 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
27c80 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
27c90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
27ca0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
27cb0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
27cc0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
27cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
27ce0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
27cf0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
27d00 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
27d10 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
27d20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
27d30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
27d40 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
27d50 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
27d60 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
27d70 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
27d80 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
27d90 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
27da0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
27db0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27dc0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
27dd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
27de0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
27df0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
27e00 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27e10 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
27e20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
27e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
27e40 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
27e50 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
27e60 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
27e70 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
27e80 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
27e90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
27ea0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
27eb0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
27ec0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
27ed0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
27ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27ef0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
27f00 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
27f10 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
27f20 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
27f30 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
27f40 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
27f50 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
27f60 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
27f70 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
27f80 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
27f90 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
27fa0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
27fb0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
27fc0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27fd0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
27fe0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
27ff0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
28000 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
28010 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28020 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
28030 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
28040 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
28050 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
28060 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
28070 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
28080 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
28090 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
280a0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
280b0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
280c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
280d0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
280e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
280f0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
28100 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
28110 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
28120 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
28130 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
28140 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
28150 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
28160 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28170 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
28180 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
28190 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
281a0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
281b0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
281c0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
281d0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
281e0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
281f0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
28200 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
28210 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
28220 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
28230 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
28240 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28250 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
28260 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
28270 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
28280 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28290 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
282a0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
282b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
282c0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
282d0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
282e0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
282f0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
28300 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
28310 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
28320 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
28330 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
28340 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
28350 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
28360 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
28370 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
28380 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
28390 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
283a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
283b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
283c0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
283d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
283e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
283f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28400 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
28410 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
28420 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
28430 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
28440 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
28450 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
28460 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
28470 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
28480 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
28490 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
284a0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
284b0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
284c0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
284d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
284e0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
284f0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
28500 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
28510 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
28530 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
28540 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
28550 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28560 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
28570 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
28580 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
28590 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
285a0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
285b0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
285c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
285d0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
285e0 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
285f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
28600 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
28610 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
28620 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
28630 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
28640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28650 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
28660 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
28670 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
28680 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
28690 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
286a0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
286b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
286c0 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
286d0 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
286e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
286f0 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
28700 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
28710 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
28720 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
28730 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
28740 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28750 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28760 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
28770 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
28780 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
28790 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
287a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
287b0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
287c0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
287d0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
287e0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
287f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28800 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
28810 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
28820 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
28830 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
28840 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28850 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
28860 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
28870 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
28880 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
28890 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
288a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
288b0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
288c0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
288d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
288e0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
288f0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
28900 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
28910 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
28920 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
28930 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
28940 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
28950 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
28960 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
28970 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
28980 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
28990 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
289a0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
289b0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
289c0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
289d0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
289e0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
289f0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
28a00 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28a10 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28a20 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28a30 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
28a40 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
28a50 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
28a60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
28a70 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
28a80 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
28a90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
28aa0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
28ab0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
28ac0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
28ad0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
28ae0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
28af0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
28b00 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
28b10 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
28b20 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
28b30 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
28b40 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
28b50 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
28b60 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
28b70 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
28b80 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
28b90 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
28ba0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
28bb0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
28bc0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
28bd0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
28be0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
28bf0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
28c00 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
28c10 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
28c20 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
28c30 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
28c40 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
28c50 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
28c60 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
28c70 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
28c80 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
28c90 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
28ca0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
28cb0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
28cc0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
28cd0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
28ce0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
28cf0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
28d00 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
28d10 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
28d20 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
28d30 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
28d40 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
28d50 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
28d60 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
28d70 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
28d80 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
28d90 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
28da0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28db0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
28dc0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
28dd0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
28de0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
28df0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
28e00 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
28e10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28e20 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
28e30 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
28e40 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
28e50 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
28e60 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
28e70 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
28e80 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
28e90 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
28ea0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
28eb0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
28ec0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
28ed0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
28ee0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
28ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
28f00 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
28f10 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
28f20 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
28f30 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
28f40 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
28f50 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
28f60 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
28f70 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
28f80 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
28f90 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
28fa0 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
28fb0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
28fc0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
28fd0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
28fe0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
28ff0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
29000 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
29010 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
29020 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
29030 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
29040 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
29050 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
29060 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
29070 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
29080 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
29090 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
290a0 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
290b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
290c0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
290d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
290e0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
290f0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
29100 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
29110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
29120 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
29130 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
29140 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
29150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
29160 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
29170 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
29180 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
29190 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
291a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
291b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
291c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
291d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
291e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
291f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
29200 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
29210 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
29220 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
29230 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
29240 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
29250 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
29260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
29270 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
29280 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29290 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
292a0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
292b0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
292c0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
292d0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
292e0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
292f0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
29300 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
29310 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29320 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
29330 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
29340 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
29350 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
29360 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
29370 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
29380 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
29390 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
293a0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
293b0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
293c0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
293d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
293e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
293f0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
29400 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
29410 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
29420 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
29430 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
29440 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
29450 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
29460 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
29470 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
29480 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
29490 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
294a0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
294b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
294c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
294d0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
294e0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
294f0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
29500 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
29510 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
29520 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
29530 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
29540 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
29550 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
29560 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
29570 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
29580 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
29590 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
295a0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
295b0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
295c0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
295d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
295e0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
295f0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
29600 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29610 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29620 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
29630 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
29640 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
29650 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
29660 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
29670 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
29680 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
29690 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
296a0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
296b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
296c0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
296d0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
296e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
296f0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
29700 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
29710 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
29720 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
29730 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
29740 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
29750 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
29760 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
29770 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
29780 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
29790 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
297a0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
297b0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
297c0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
297d0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
297e0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
297f0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
29800 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
29810 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
29820 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
29830 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
29840 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
29850 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
29860 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
29870 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
29880 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
29890 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
298a0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
298b0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
298c0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
298d0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
298e0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
298f0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
29900 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
29910 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
29920 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
29930 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
29940 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
29950 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
29960 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
29970 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
29980 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
29990 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
299a0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
299b0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
299c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
299d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
299e0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
299f0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
29a00 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
29a10 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
29a20 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
29a30 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
29a40 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
29a50 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
29a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29a70 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
29a80 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
29a90 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
29aa0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
29ab0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
29ac0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
29ad0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
29ae0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
29af0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
29b00 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
29b10 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
29b20 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
29b30 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
29b40 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
29b50 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
29b60 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
29b70 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
29b80 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
29b90 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
29ba0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
29bb0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
29bc0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
29bd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29be0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29bf0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
29c00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29c10 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
29c20 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
29c30 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
29c40 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
29c50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29c60 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
29c70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29c80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
29c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29ca0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
29cb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29cc0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
29cd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29ce0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
29cf0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29d00 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
29d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29d20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
29d30 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
29d40 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
29d50 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
29d60 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
29d70 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
29d80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
29d90 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
29da0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
29db0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
29dc0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
29dd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29de0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
29df0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29e00 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
29e10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29e20 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
29e30 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
29e40 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
29e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
29e70 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
29e80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29e90 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29ea0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
29eb0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29ec0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
29ed0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
29ee0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
29ef0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29f00 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
29f10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29f20 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
29f30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29f40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
29f50 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
29f60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
29f70 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
29f80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
29f90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
29fa0 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
29fb0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
29fc0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
29fd0 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
29fe0 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
29ff0 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2a000 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2a010 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2a020 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2a030 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2a040 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2a050 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a060 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2a070 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2a080 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a090 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2a0a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a0b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2a0c0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2a0d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a0e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2a0f0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2a100 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a110 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2a120 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a130 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2a140 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2a150 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2a160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a170 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2a180 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2a190 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2a1a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2a1b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a1c0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2a1d0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2a1e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a1f0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2a200 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2a210 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2a230 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2a240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a250 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2a260 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2a270 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2a280 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2a290 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2a2a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2a2b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a2c0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a2d0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2a2e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2a2f0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2a300 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a310 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2a320 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2a330 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a340 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2a350 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2a360 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a370 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2a380 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a390 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a3a0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2a3b0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2a3c0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2a3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a3e0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2a3f0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2a400 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a410 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2a420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2a430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a440 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2a450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a460 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2a470 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2a480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a490 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2a4a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a4b0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2a4c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2a4d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2a4e0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2a4f0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2a500 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2a510 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2a520 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2a530 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a540 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2a550 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2a560 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2a570 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2a580 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2a590 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2a5a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2a5b0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2a5c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2a5d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2a5e0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2a5f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2a600 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2a610 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2a620 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a630 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2a640 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2a650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2a660 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  pare Flags.**.**
2a670 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2a680 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2a690 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62  flags that can b
2a6a0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  e passed into.**
2a6b0 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72   "prepFlags" par
2a6c0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73  ameter of the [s
2a6d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a6e0 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  3()] and.** [sql
2a6f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a700 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e  3()] interfaces.
2a710 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73  .**.** New flags
2a720 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2a730 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2a740 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2a750 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2a760 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2a770 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  STENT]] ^(<dt>SQ
2a780 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2a790 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  SISTENT</dt>.** 
2a7a0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2a7b0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2a7c0 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74  T flag is a hint
2a7d0 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c   to the query pl
2a7e0 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  anner.** that th
2a7f0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a800 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74  ment will be ret
2a810 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67  ained for a long
2a820 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f   time and.** pro
2a830 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e  bably reused man
2a840 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68  y times.)^ ^With
2a850 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b  out this flag, [
2a860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a870 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  v3()].** and [sq
2a880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a890 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61  v3()] assume tha
2a8a0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2a8b0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a  tatement will .*
2a8c0 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f  * be used just o
2a8d0 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61  nce or at most a
2a8e0 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74   few times and t
2a8f0 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
2a900 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2a910 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61  finalize()] rela
2a920 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65  tively soon. The
2a930 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2a940 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20  ntation acts.** 
2a950 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20  on this hint by 
2a960 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65  avoiding the use
2a970 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d   of [lookaside m
2a980 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74  emory] so as not
2a990 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74   to.** deplete t
2a9a0 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65  he limited store
2a9b0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
2a9c0 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72  mory. Future ver
2a9d0 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69  sions of.** SQLi
2a9e0 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68  te may act on th
2a9f0 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e  is hint differen
2aa00 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  tly..** </dl>.*/
2aa10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2aa20 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2aa30 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2aa40 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2aa50 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2aa60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2aa70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2aa80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2aa90 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2aaa0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2aab0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2aac0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2aad0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2aae0 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2aaf0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2ab00 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2ab10 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2ab20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2ab30 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2ab40 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2ab50 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2ab60 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2ab70 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2ab80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab90 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2aba0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2abb0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2abc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2abd0 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2abe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2abf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2ac00 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2ac10 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2ac20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ac30 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2ac40 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2ac50 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2ac60 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2ac70 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2ac80 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2ac90 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2aca0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2acb0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2acc0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2acd0 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2ace0 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2acf0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2ad00 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2ad10 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2ad20 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2ad30 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2ad40 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2ad50 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2ad60 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2ad70 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2ad80 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2ad90 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2ada0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2adb0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2adc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2add0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2ade0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2adf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2ae00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2ae10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2ae20 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2ae30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2ae40 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2ae50 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2ae60 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2ae70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2ae80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2ae90 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2aea0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2aeb0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2aec0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2aed0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2aee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2aef0 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2af00 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2af10 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2af20 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2af30 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2af40 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2af50 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2af60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2af70 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2af80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2af90 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2afa0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2afb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2afc0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2afd0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2afe0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2aff0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2b000 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2b010 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2b020 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b030 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2b040 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2b050 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2b060 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2b070 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2b080 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2b090 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2b0a0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2b0b0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2b0c0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2b0d0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2b0e0 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2b0f0 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2b100 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2b110 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2b120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2b130 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2b140 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2b150 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2b160 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2b170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2b180 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2b190 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2b1a0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2b1b0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2b1c0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2b1d0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2b1e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2b1f0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2b200 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2b210 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2b220 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2b230 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2b240 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2b250 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2b260 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2b270 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2b280 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2b290 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2b2a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b2b0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2b2c0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2b2d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2b2e0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2b2f0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2b300 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2b310 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2b320 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2b330 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2b340 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2b350 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2b360 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2b370 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2b380 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2b390 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2b3a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2b3b0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2b3c0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2b3d0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2b3e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b3f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2b400 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2b410 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2b420 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2b430 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2b440 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2b450 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2b460 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2b470 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2b480 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2b490 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2b4a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2b4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b4c0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2b4d0 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2b4e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b4f0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b500 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b510 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2b520 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2b530 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2b540 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2b550 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2b560 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2b570 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b580 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2b590 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2b5a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2b5b0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2b5c0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2b5d0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2b5e0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2b5f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b600 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2b610 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2b620 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2b630 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2b640 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2b650 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2b660 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2b670 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b680 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2b690 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2b6a0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2b6b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2b6c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2b6d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b6e0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2b6f0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2b700 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2b710 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2b720 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2b730 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2b740 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2b750 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2b760 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2b770 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2b780 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2b790 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2b7a0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2b7b0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2b7c0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2b7d0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2b7e0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2b7f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2b800 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2b810 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2b820 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2b830 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2b840 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2b850 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2b860 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2b870 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2b880 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2b890 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2b8a0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2b8b0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2b8c0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2b8d0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2b8e0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2b8f0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2b900 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2b910 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2b920 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b930 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2b940 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2b950 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2b960 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2b970 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2b980 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2b990 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2b9a0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2b9b0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2b9c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2b9d0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2b9e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2b9f0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2ba00 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2ba10 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2ba20 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2ba30 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2ba40 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2ba50 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2ba60 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2ba70 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2ba80 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2ba90 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2baa0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2bab0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2bac0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2bad0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2bae0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2baf0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2bb00 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2bb10 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2bb20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2bb30 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2bb40 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2bb50 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2bb60 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2bb70 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2bb80 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2bb90 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2bba0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2bbb0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2bbc0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2bbd0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2bbe0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2bbf0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2bc00 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2bc10 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2bc20 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2bc30 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2bc40 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2bc50 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2bc60 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2bc70 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2bc80 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </ol>.**.** <p>^
2bc90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bca0 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2bcb0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2bcc0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2bcd0 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2bce0 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2bcf0 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2bd00 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2bd10 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2bd20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2bd30 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2bd40 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2bd50 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2bd60 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2bd70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bd80 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2bd90 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2bda0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2bdb0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2bdc0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2bdd0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2bde0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bdf0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2be00 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2be10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2be20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2be30 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2be40 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2be50 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2be60 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2be70 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2be80 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2be90 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2bea0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2beb0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2bec0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2bed0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2bee0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2bef0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2bf00 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2bf10 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2bf20 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2bf30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2bf40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2bf50 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2bf60 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2bf70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2bf80 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2bf90 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2bfa0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2bfb0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2bfc0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2bfd0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2bfe0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2bff0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c000 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c010 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c020 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c030 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c040 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c050 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c060 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c070 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c080 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2c090 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c0a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c0b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c0c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c0d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c0e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c0f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c100 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c110 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c120 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c130 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2c140 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2c150 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2c160 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2c170 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2c180 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c190 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c1a0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c1b0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2c1c0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c1d0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c1e0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c1f0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c200 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2c210 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c220 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c230 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c240 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2c250 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c260 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2c270 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2c280 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2c290 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2c2a0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2c2b0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2c2c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c2d0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c2e0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c2f0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2c300 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c310 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c320 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c330 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2c340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c350 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2c360 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c370 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c380 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c390 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2c3a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c3b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2c3c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2c3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c3e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2c3f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2c400 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2c410 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c420 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c430 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c440 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2c450 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c460 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c470 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c480 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2c490 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2c4a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c4b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c4c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c4d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2c4e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c4f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2c500 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2c510 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c520 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c530 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c540 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c550 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2c560 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2c570 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2c580 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2c590 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2c5a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2c5b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2c5c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2c5d0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2c5e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2c5f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2c600 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2c610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c620 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2c630 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2c640 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c650 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2c660 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2c670 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2c680 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2c690 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2c6a0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2c6b0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2c6c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c6d0 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2c6e0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2c6f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2c700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c710 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2c720 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c730 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2c740 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2c750 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2c760 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2c770 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c780 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c790 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2c7a0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2c7b0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2c7c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c7d0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2c7e0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2c7f0 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2c800 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2c810 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2c820 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2c830 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2c840 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2c850 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2c860 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2c870 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2c880 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2c890 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2c8a0 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2c8b0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2c8c0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2c8d0 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2c8e0 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2c8f0 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2c900 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2c910 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2c920 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2c930 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2c940 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2c950 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2c960 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2c970 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2c980 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2c990 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2c9a0 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2c9b0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2c9c0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2c9d0 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2c9e0 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2c9f0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2ca00 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2ca10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2ca20 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2ca30 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2ca40 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2ca50 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2ca60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2ca70 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2ca80 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2ca90 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2caa0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2cab0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2cac0 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2cad0 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2cae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2caf0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2cb00 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2cb10 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2cb20 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2cb30 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2cb40 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2cb50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2cb60 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2cb70 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2cb80 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2cb90 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2cba0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2cbb0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2cbc0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2cbd0 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2cbe0 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2cbf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2cc00 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2cc10 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2cc20 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2cc30 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2cc40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2cc50 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2cc60 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2cc70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2cc80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2cc90 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2cca0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2ccb0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2ccc0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2ccd0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2cce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ccf0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2cd00 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2cd10 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2cd20 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2cd30 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2cd40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cd50 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2cd60 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2cd70 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2cd80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2cd90 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2cda0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2cdb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2cdc0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2cdd0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2cde0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2cdf0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2ce00 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2ce10 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2ce20 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2ce30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ce40 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2ce50 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2ce60 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2ce70 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2ce80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2ce90 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2cea0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2ceb0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2cec0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2ced0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2cee0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2cef0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2cf00 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2cf10 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2cf20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2cf30 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2cf40 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2cf50 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2cf60 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2cf70 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2cf80 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2cf90 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2cfa0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2cfb0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2cfc0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2cfd0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2cfe0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2cff0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2d000 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2d010 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2d020 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2d030 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d040 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2d050 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2d060 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2d070 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2d080 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2d090 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2d0a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2d0b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2d0c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2d0d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2d0e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2d0f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2d100 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2d110 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2d120 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2d130 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2d140 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2d150 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2d160 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2d170 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2d180 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2d190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2d1a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2d1b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2d1c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d1e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2d1f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d200 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2d210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d220 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2d230 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2d240 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2d250 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2d260 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2d270 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2d280 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2d290 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2d2a0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2d2b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2d2c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2d2d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2d2e0 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2d2f0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2d300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2d310 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2d320 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d340 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2d350 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2d360 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2d370 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2d380 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2d3a0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2d3b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2d3c0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2d3d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d3e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2d3f0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2d400 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2d410 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2d420 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2d430 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2d440 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2d450 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2d460 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2d470 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2d480 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2d490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2d4a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2d4b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2d4c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2d4d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2d4e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2d4f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2d500 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2d510 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2d520 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2d530 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2d540 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d550 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2d560 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2d570 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2d580 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2d590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2d5a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2d5b0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2d5c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2d5d0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2d5e0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2d5f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2d600 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2d610 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2d620 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2d630 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2d640 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2d650 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2d660 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2d670 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2d680 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2d690 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2d6a0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2d6b0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2d6c0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2d6d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2d6e0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2d6f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d700 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2d710 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2d720 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2d730 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2d740 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2d750 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d760 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2d770 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2d780 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d790 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2d7a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2d7b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2d7c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2d7d0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2d7e0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2d7f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2d800 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2d810 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2d820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2d830 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2d840 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2d850 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2d860 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2d870 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2d880 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2d890 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2d8a0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2d8b0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2d8c0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2d8d0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2d8e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2d8f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2d900 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2d910 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2d920 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2d930 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2d940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2d950 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2d960 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2d970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2d980 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2d990 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2d9a0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2d9b0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2d9c0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2d9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2d9e0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2d9f0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2da00 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2da10 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2da20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2da30 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2da40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2da50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2da60 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2da70 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2da80 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2da90 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2daa0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2dab0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2dac0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2dad0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2dae0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2daf0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2db00 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2db10 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2db20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2db30 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2db40 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2db50 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2db60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2db70 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2db80 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2db90 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2dba0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2dbb0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2dbc0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2dbd0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2dbe0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2dbf0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2dc00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2dc10 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2dc20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2dc30 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2dc40 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2dc50 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2dc60 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2dc70 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2dc80 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2dc90 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2dca0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2dcb0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2dcc0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2dcd0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2dce0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2dcf0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2dd00 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2dd10 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2dd20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2dd30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dd40 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2dd50 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2dd60 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2dd70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2dd80 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2dd90 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2dda0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2ddb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ddc0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2ddd0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2dde0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2ddf0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2de00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2de10 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2de20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2de30 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2de40 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2de50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2de60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2de70 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2de80 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2de90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2dea0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2deb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2dec0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2ded0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2dee0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2def0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2df00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2df10 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2df20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2df30 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2df40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2df50 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2df60 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2df70 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2df80 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2df90 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2dfa0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2dfb0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2dfc0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2dfd0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2dfe0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2dff0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2e000 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2e010 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2e020 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2e030 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2e040 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2e050 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2e060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2e080 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2e090 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e0a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e0b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2e0c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2e0d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2e0e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e0f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2e100 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2e110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2e120 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2e130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2e140 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2e150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2e160 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2e170 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e180 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2e190 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e1a0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2e1b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e1c0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2e1d0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2e1e0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2e1f0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2e200 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e210 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2e220 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2e230 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2e240 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2e250 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2e260 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2e270 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2e280 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2e290 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2e2a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e2b0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2e2c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2e2d0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2e2e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e2f0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2e300 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2e310 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2e320 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2e330 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2e340 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2e350 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2e360 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2e370 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2e380 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2e390 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2e3a0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2e3b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2e3c0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2e3d0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2e3e0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2e3f0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2e400 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2e410 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2e420 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2e430 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2e440 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2e450 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2e460 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2e470 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2e480 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2e490 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2e4a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2e4b0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2e4c0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2e4d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e4e0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2e4f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2e500 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2e510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2e520 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2e530 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e540 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2e550 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2e560 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2e570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2e580 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e590 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2e5a0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2e5b0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2e5c0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2e5d0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2e5e0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2e5f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2e600 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2e610 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2e620 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2e630 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2e640 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2e650 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2e660 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2e670 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2e680 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2e690 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2e6a0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2e6b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2e6c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e6d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2e6e0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2e6f0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2e700 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2e710 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2e720 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2e730 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2e740 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2e750 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2e760 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2e770 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2e780 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2e790 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2e7a0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2e7b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2e7c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2e7d0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2e7e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2e7f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2e800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2e810 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2e820 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e830 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2e840 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2e850 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2e860 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2e870 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2e880 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2e890 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2e8a0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2e8b0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2e8c0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2e8d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2e8e0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2e8f0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2e900 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2e910 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2e920 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2e930 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2e940 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2e950 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2e960 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2e970 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2e980 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2e990 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2e9a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2e9b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e9c0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2e9d0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2e9e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e9f0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2ea00 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2ea10 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ea20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2ea30 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2ea40 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2ea50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ea60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2ea70 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2ea80 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2ea90 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2eaa0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2eab0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2eac0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2ead0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2eae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2eaf0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2eb00 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2eb10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2eb20 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2eb30 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2eb40 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2eb50 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2eb60 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2eb70 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2eb80 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2eb90 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2eba0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2ebb0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2ebc0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2ebd0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2ebe0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2ebf0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2ec00 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2ec10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2ec20 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2ec30 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2ec40 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2ec50 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2ec60 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2ec70 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2ec80 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2ec90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2eca0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2ecb0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2ecc0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2ecd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2ece0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2ecf0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2ed00 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2ed10 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2ed20 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2ed30 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2ed40 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2ed50 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2ed60 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2ed70 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2ed80 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2ed90 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2eda0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2edb0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2edc0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2edd0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2ede0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2edf0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2ee00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2ee10 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2ee20 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2ee30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2ee40 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2ee50 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2ee60 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2ee70 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2ee80 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2ee90 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2eea0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2eeb0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2eec0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2eed0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2eee0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2eef0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2ef00 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2ef10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2ef20 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2ef30 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2ef40 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2ef50 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2ef60 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2ef70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2ef80 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2ef90 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2efa0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2efb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2efc0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2efd0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2efe0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2eff0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2f000 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2f010 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2f020 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2f030 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2f040 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2f050 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2f060 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2f070 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2f080 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f090 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2f0a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2f0c0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2f0d0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2f0e0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2f0f0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2f100 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2f110 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2f120 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2f130 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2f140 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2f150 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2f160 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2f170 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2f180 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2f190 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2f1a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2f1b0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2f1c0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2f1d0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2f1e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2f1f0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2f200 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2f210 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2f220 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2f230 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2f240 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2f250 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2f260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2f270 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
2f280 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
2f290 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
2f2a0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
2f2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f2c0 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
2f2d0 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
2f2e0 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
2f2f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f300 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
2f310 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
2f320 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
2f330 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
2f340 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
2f350 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2f360 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
2f370 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
2f380 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
2f390 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
2f3a0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
2f3b0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
2f3c0 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
2f3d0 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
2f3e0 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
2f3f0 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
2f400 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
2f410 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
2f420 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2f430 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
2f440 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
2f450 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
2f460 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
2f470 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
2f480 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2f490 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2f4a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2f4b0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2f4c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2f4d0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2f4e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2f4f0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2f500 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2f510 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2f520 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2f530 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2f540 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2f550 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2f560 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2f570 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2f580 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2f590 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2f5a0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2f5b0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2f5c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f5d0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2f5e0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2f5f0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2f600 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2f610 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2f620 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2f630 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2f640 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2f650 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2f660 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2f670 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2f680 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2f690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f6a0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2f6b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f6c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2f6d0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2f6e0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2f6f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2f700 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2f710 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2f720 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2f730 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2f740 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2f750 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2f760 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2f770 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2f780 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2f790 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2f7a0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2f7b0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2f7c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2f7d0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2f7e0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2f7f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2f800 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2f810 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2f820 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f830 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f840 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2f850 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f860 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2f870 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2f880 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2f890 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2f8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f8b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f8c0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2f8d0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2f8e0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2f8f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2f900 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f910 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2f920 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2f930 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2f940 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2f950 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2f960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2f970 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2f980 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2f990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f9a0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2f9b0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2f9c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f9d0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2f9e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2f9f0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2fa00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2fa10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fa20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2fa30 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2fa40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2fa50 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2fa60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2fa70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fa80 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2fa90 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2faa0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2fab0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2fac0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2fad0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2fae0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2faf0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2fb00 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2fb10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fb20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2fb30 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2fb40 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2fb50 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2fb60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fb70 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2fb80 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2fb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2fba0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
2fbb0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
2fbc0 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
2fbd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2fbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2fbf0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2fc00 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2fc10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2fc20 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
2fc30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fc40 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2fc50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fc60 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2fc70 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2fc80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2fc90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2fca0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2fcb0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2fcc0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2fcd0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2fce0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2fcf0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2fd00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2fd10 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2fd20 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2fd30 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2fd40 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2fd50 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2fd60 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2fd70 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2fd80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2fd90 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2fda0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2fdb0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2fdc0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2fdd0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2fde0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2fdf0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2fe00 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2fe10 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2fe20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2fe30 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2fe40 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2fe50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2fe60 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2fe70 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2fe80 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2fe90 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2fea0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2feb0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2fec0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2fed0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2fee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2fef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ff00 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2ff10 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2ff20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ff30 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2ff40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ff50 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2ff60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2ff70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ff80 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2ff90 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
2ffa0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ffb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2ffc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ffd0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2ffe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fff0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
30000 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
30010 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
30020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30030 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
30040 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
30050 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
30060 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
30070 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
30080 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
30090 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
300a0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
300b0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
300c0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
300d0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
300e0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
300f0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
30100 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
30110 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
30120 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
30130 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
30140 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
30150 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
30160 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
30170 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
30180 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
30190 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
301a0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
301b0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
301c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
301d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
301e0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
301f0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
30200 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
30210 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
30220 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
30230 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
30240 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
30250 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
30260 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
30270 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
30280 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
30290 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
302a0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
302b0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
302c0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
302d0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
302e0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
302f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30300 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
30310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30320 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
30330 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30340 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30350 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
30360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30370 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
30380 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
30390 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
303a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
303b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
303c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
303d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
303e0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
303f0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
30400 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
30410 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
30420 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
30430 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30440 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
30450 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
30460 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
30470 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
30480 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
30490 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
304a0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
304b0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
304c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
304d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
304e0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
304f0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
30500 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
30510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
30520 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
30530 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
30540 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
30550 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
30560 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
30570 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
30580 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
30590 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
305a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
305b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
305c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
305d0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
305e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
305f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30600 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30610 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30620 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
30630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30650 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30660 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30670 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
30680 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
30690 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
306a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
306b0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
306c0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
306d0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
306e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
306f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
30700 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
30710 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
30720 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
30730 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
30740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30750 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
30760 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30770 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
30780 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
30790 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
307a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
307b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
307c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
307d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
307e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
307f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
30800 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
30810 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
30820 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30830 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
30840 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
30850 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
30860 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
30870 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30880 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
30890 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
308a0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
308b0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
308c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
308d0 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
308e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
308f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
30900 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
30910 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
30920 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
30930 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
30940 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
30950 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
30960 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
30970 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
30980 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
30990 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
309a0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
309b0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
309c0 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
309d0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
309e0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
309f0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
30a00 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
30a10 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
30a20 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
30a30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
30a40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
30a50 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
30a60 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
30a70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30a80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30a90 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
30aa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
30ab0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30ac0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30ad0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
30ae0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
30af0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
30b00 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
30b10 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
30b20 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
30b30 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
30b40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
30b50 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
30b60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
30b80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
30b90 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
30ba0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30bb0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
30bc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
30bd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
30be0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
30bf0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
30c00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
30c10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30c20 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
30c30 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
30c40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
30c50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
30c60 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
30c70 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
30c80 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
30c90 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
30ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
30cb0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
30cc0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
30cd0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
30ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30cf0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
30d00 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
30d10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
30d20 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
30d30 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
30d40 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
30d50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
30d60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30d70 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
30d80 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
30d90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
30da0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
30db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
30dc0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
30dd0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
30de0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
30df0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
30e00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
30e10 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
30e20 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
30e30 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
30e40 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
30e50 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
30e60 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
30e70 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
30e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
30e90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
30ea0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
30eb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
30ec0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
30ed0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
30ee0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
30ef0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
30f00 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
30f10 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
30f20 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
30f30 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
30f40 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
30f50 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
30f60 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
30f70 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
30f80 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
30f90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
30fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
30fb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30fc0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
30fd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30fe0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
30ff0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
31000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31010 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
31020 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
31030 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31040 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31050 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
31060 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
31070 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
31080 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31090 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
310a0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
310b0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
310c0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
310d0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
310e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
310f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
31100 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
31110 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
31120 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
31130 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
31140 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
31150 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
31160 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
31170 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
31180 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
31190 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
311a0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
311b0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
311c0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
311d0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
311e0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
311f0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31200 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
31210 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
31220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
31230 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
31240 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
31250 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
31260 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
31270 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
31280 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
31290 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
312a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
312b0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
312c0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
312d0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
312e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
312f0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
31300 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
31310 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
31320 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
31330 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
31340 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
31350 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
31360 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31370 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
31380 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
31390 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
313a0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
313b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
313c0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
313d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
313e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
313f0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
31400 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
31410 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
31420 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
31430 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31440 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31450 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
31460 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
31470 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
31480 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
31490 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
314a0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
314b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
314c0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
314d0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
314e0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
314f0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
31500 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
31510 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
31520 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
31530 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
31540 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
31550 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31560 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
31570 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
31580 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
31590 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
315a0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
315b0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
315c0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
315d0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
315e0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
315f0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
31600 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
31610 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
31620 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
31630 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
31640 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
31650 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
31660 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
31670 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
31680 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
31690 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
316a0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
316b0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
316c0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
316d0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
316e0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
316f0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
31700 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
31710 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
31720 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
31730 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31740 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
31750 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
31760 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
31770 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
31780 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
31790 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
317a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
317b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
317c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
317d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
317e0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
317f0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
31800 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
31810 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
31820 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
31830 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
31840 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
31850 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
31860 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
31870 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
31880 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
318a0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
318b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
318c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
318d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
318e0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
318f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31900 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
31910 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
31920 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
31930 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
31940 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
31950 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
31960 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31970 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
31980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
31990 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
319a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
319b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
319c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
319d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
319e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
319f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
31a00 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
31a10 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
31a20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31a30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
31a40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31a50 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
31a60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31a70 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
31a80 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
31a90 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
31aa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
31ab0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
31ac0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
31ad0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
31ae0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
31af0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
31b00 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
31b10 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
31b20 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
31b30 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
31b40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
31b50 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
31b60 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
31b70 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
31b80 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
31b90 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
31ba0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
31bb0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
31bc0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
31bd0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
31be0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
31bf0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
31c00 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
31c10 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
31c20 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
31c30 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
31c40 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
31c50 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
31c60 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
31c70 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
31c80 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
31c90 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
31ca0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
31cb0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
31cc0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
31cd0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
31ce0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
31cf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
31d00 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
31d10 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
31d20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
31d30 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
31d40 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
31d50 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
31d60 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
31d70 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
31d80 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
31d90 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
31da0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
31db0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
31dc0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
31dd0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
31de0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
31df0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
31e00 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
31e10 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
31e20 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
31e30 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
31e40 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
31e50 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
31e60 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
31e70 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
31e80 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
31e90 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
31ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
31eb0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
31ec0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
31ed0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31ee0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
31ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
31f00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
31f10 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
31f20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
31f30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31f40 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
31f50 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
31f60 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
31f70 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
31f80 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
31f90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31fa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
31fb0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
31fc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31fd0 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
31fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31ff0 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
32000 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
32010 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
32020 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
32030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32040 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
32050 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
32060 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
32070 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
32080 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
32090 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
320a0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
320b0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
320c0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
320d0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
320e0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
320f0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
32100 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
32110 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
32120 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
32130 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
32140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32150 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
32160 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32170 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
32180 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
32190 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
321a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
321b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
321c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
321d0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
321e0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
321f0 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
32200 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
32210 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
32220 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
32230 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
32240 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
32250 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
32260 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
32270 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
32280 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
32290 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
322a0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
322b0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
322c0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
322d0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
322e0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
322f0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
32300 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
32310 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
32320 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
32330 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
32340 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
32350 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
32360 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
32370 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
32380 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
32390 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
323a0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
323b0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
323c0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
323d0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
323e0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
323f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
32400 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
32410 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
32420 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
32430 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
32440 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
32450 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
32460 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32470 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
32480 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
32490 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
324a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
324b0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
324c0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
324d0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
324e0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
324f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
32500 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
32510 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
32520 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
32530 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
32540 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
32550 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
32560 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
32570 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
32580 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
32590 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
325a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
325b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
325c0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
325d0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
325e0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
325f0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
32600 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
32610 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
32620 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
32630 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
32640 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
32650 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
32660 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
32670 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
32680 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
32690 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
326a0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
326b0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
326c0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
326d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
326e0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
326f0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
32700 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
32710 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
32720 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
32730 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
32740 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
32750 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
32760 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
32770 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
32780 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
32790 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
327a0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
327b0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
327c0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
327d0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
327e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
327f0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
32800 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
32810 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32820 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
32830 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
32840 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
32850 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
32860 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
32870 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
32880 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
32890 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
328a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
328b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
328c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
328d0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
328e0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
328f0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
32900 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
32910 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
32920 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
32930 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
32940 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
32950 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
32960 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
32970 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
32980 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
32990 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
329a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
329b0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
329c0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
329d0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
329e0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
329f0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
32a00 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
32a10 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
32a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
32a30 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
32a40 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
32a50 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
32a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32a70 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
32a80 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
32a90 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
32aa0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
32ab0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
32ac0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
32ad0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
32ae0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
32af0 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
32b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32b10 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
32b20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
32b30 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
32b40 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
32b50 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
32b60 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
32b70 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
32b80 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
32b90 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
32ba0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
32bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32bc0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
32bd0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
32be0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
32bf0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32c00 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
32c10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
32c20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
32c30 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
32c40 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
32c50 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
32c60 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
32c70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
32c80 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
32c90 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
32ca0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
32cb0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
32cc0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
32cd0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
32ce0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
32cf0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
32d00 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
32d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
32d20 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
32d30 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
32d40 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
32d50 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
32d60 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
32d70 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
32d80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
32d90 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
32da0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
32db0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
32dc0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
32dd0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
32de0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
32df0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
32e00 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
32e10 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
32e20 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
32e30 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
32e40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
32e50 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
32e60 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
32e70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
32e80 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
32e90 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
32ea0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
32eb0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
32ec0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
32ed0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
32ee0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
32ef0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
32f00 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
32f10 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
32f20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
32f30 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
32f40 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
32f50 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
32f60 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
32f70 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
32f80 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
32f90 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
32fa0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
32fb0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
32fc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
32fd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
32fe0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
32ff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33000 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
33010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33020 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
33030 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
33040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33050 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
33060 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
33070 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
33080 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
33090 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
330a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
330b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
330c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
330d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
330e0 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
330f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
33100 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
33110 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
33120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33130 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
33140 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
33150 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
33160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
33190 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
331a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
331b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
331c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
331d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
331e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
331f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
33200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33210 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
33220 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
33230 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
33240 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
33250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33260 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
33270 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
33280 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
33290 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
332a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
332b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
332c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
332d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
332e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
332f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
33300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33310 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
33320 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
33330 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
33340 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33350 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
33360 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
33370 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
33380 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33390 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
333a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
333b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
333c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
333d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
333e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
333f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
33400 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
33410 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
33420 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
33430 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
33440 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
33450 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
33460 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
33470 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
33480 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
33490 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
334a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
334b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
334c0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
334d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
334e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
334f0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
33500 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
33510 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
33520 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
33530 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
33540 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
33550 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
33560 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
33570 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
33580 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33590 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
335a0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
335b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
335c0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
335d0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
335e0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
335f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33600 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
33610 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
33620 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
33630 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
33640 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
33650 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
33660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
33670 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
33680 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
33690 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
336a0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
336b0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
336c0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
336d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
336e0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
336f0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
33700 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
33710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33720 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
33730 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
33740 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33750 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
33760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
33770 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
33780 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
33790 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
337a0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
337b0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
337c0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
337d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
337e0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
337f0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
33800 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
33810 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
33820 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
33830 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
33840 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33850 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
33860 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
33870 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
33880 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
33890 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
338a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
338b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
338c0 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
338d0 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
338e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
338f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33900 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
33910 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
33920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
33940 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
33950 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
33960 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
33970 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33980 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
33990 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
339a0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
339b0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
339c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
339d0 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
339e0 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
339f0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33a00 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33a10 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
33a20 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
33a30 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
33a40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
33a60 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
33a70 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
33a80 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
33a90 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
33aa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33ab0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
33ac0 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
33ad0 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
33ae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33b00 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
33b10 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
33b20 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
33b30 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
33b40 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
33b50 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33b60 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
33b70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
33b80 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
33b90 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
33ba0 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
33bb0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
33bc0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33bd0 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
33be0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
33bf0 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
33c00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
33c10 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
33c20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
33c30 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
33c40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
33c50 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
33c60 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
33c70 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
33c80 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
33c90 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
33ca0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
33cb0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
33cc0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
33cd0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
33ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33cf0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
33d00 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
33d10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
33d20 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
33d30 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
33d40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
33d50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
33d60 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
33d70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
33d80 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
33d90 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
33da0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
33db0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
33dc0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
33dd0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
33de0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
33df0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
33e00 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
33e10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33e20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
33e30 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
33e40 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
33e50 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33e60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
33e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
33e80 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
33e90 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
33ea0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
33eb0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
33ec0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
33ed0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
33ee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
33ef0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
33f00 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
33f10 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
33f20 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
33f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33f40 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
33f50 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
33f60 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
33f70 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
33f80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33f90 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
33fa0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
33fb0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
33fc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
33fd0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
33fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33ff0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
34000 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
34010 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
34020 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
34030 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
34040 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
34050 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
34060 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34070 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
34080 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
34090 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
340a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
340b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
340c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
340d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
340e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
340f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
34100 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
34110 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34120 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34130 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
34140 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
34150 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
34160 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
34170 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
34180 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
34190 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
341a0 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
341b0 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
341c0 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
341d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
341e0 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
341f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
34200 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
34210 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
34220 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
34230 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
34240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34250 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
34260 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
34270 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
34280 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
34290 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
342a0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
342b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
342c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
342d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
342e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
342f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
34300 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
34310 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
34320 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
34330 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
34340 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
34350 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
34360 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
34370 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
34380 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
34390 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
343a0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
343b0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
343c0 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
343d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
343e0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
343f0 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
34400 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
34410 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
34420 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
34430 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
34440 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
34450 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
34460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34470 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
34480 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
34490 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
344a0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
344b0 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
344c0 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
344d0 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
344e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
344f0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
34500 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
34510 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
34520 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
34530 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
34540 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
34550 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
34560 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
34570 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
34580 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34590 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
345a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
345b0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
345c0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
345d0 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
345e0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
345f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
34600 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
34610 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
34620 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
34630 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
34640 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
34650 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34660 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
34670 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34680 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
34690 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
346a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
346b0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
346c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
346d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
346e0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
346f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34700 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
34710 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
34720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34730 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
34740 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
34750 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
34760 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34770 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
34780 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34790 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
347a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
347b0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
347c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
347d0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
347e0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
347f0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
34800 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34810 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34820 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34830 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34840 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34850 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34860 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
34870 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
34880 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34890 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
348a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
348b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
348c0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
348d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
348e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
348f0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
34900 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34910 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34920 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
34930 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34940 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
34950 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
34960 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
34970 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
34980 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34990 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
349a0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
349b0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
349c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
349d0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
349e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
349f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
34a00 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
34a10 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
34a20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
34a30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
34a40 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
34a50 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34a60 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
34a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34a80 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
34a90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
34aa0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
34ab0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
34ac0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
34ad0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
34ae0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
34af0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
34b00 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
34b10 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
34b20 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
34b30 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
34b40 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
34b50 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
34b60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34b70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
34b90 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
34ba0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
34bb0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
34bc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
34bd0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
34be0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
34bf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
34c00 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
34c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34c20 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
34c30 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
34c40 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
34c50 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
34c60 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
34c70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
34c80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
34c90 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
34ca0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
34cb0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
34cc0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
34cd0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
34ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
34cf0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
34d00 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
34d10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34d20 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
34d30 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
34d40 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
34d50 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
34d60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
34d70 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
34d80 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
34d90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
34da0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
34db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34dc0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
34dd0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
34de0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34df0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
34e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34e10 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
34e20 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
34e30 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
34e40 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
34e50 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
34e60 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
34e70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34e80 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
34e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34ea0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
34eb0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
34ec0 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
34ed0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
34ee0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
34ef0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
34f00 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
34f10 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
34f20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
34f30 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
34f40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34f50 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
34f60 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
34f70 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
34f80 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
34f90 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
34fa0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
34fb0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
34fc0 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
34fd0 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
34fe0 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
34ff0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
35000 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
35010 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
35020 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
35030 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
35040 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
35050 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
35060 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
35070 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
35080 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
35090 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
350a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
350b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
350c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
350d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
350e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
350f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
35100 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
35110 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
35120 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
35130 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
35140 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
35150 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
35160 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35170 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
35180 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
35190 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
351a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
351b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
351c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
351d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
351e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
351f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
35200 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
35210 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
35220 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
35230 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
35240 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35250 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
35260 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
35270 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
35280 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
35290 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
352a0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
352b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
352c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
352d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
352e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
352f0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
35300 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
35310 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
35320 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35330 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35340 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35350 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
35360 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
35370 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
35380 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
35390 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
353a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
353b0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
353c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
353d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
353e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
353f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35400 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35410 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35420 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
35440 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
35450 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
35460 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
35470 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
35480 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
35490 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
354a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
354b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
354c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
354d0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
354e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
354f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35500 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
35510 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
35520 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
35530 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
35540 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
35550 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
35560 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
35570 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
35580 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
35590 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
355a0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
355b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
355c0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
355d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
355e0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
355f0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
35600 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
35610 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
35620 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
35630 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
35640 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
35650 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
35660 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35670 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
35680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35690 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
356a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
356b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
356c0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
356d0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
356e0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
356f0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
35700 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
35710 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35720 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
35730 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
35740 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35750 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
35760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35770 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
35780 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
35790 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
357a0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
357b0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
357c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
357d0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
357e0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
357f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
35800 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
35810 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
35820 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
35830 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
35840 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
35850 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
35860 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
35870 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
35880 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
35890 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
358a0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
358b0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
358c0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
358d0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
358e0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
358f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
35900 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
35910 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
35920 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
35930 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
35940 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
35950 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
35960 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
35970 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
35980 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
35990 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
359a0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
359b0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
359c0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
359d0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
359e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
359f0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
35a00 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
35a10 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
35a20 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
35a30 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
35a40 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
35a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35a60 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
35a70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35a80 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
35a90 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
35aa0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
35ab0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
35ac0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
35ad0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
35ae0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
35af0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
35b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35b10 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
35b20 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
35b30 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
35b40 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
35b50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
35b60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35b70 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
35b80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35b90 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
35ba0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
35bb0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
35bc0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
35bd0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
35be0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
35bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
35c00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
35c10 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
35c20 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
35c30 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
35c40 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
35c50 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
35c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35c70 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
35c80 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
35c90 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
35ca0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
35cb0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
35cc0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
35cd0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
35ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35cf0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
35d00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
35d10 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
35d20 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
35d30 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
35d40 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
35d50 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
35d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
35d70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
35d80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
35d90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
35da0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
35db0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
35dc0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
35dd0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
35de0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
35df0 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
35e00 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
35e10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
35e20 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
35e30 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
35e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35e50 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
35e60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
35e70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
35e80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
35e90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
35ea0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
35eb0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
35ec0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
35ed0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
35ee0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
35ef0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
35f00 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
35f10 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
35f20 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
35f30 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
35f40 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
35f50 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
35f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
35f70 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
35f80 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
35f90 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
35fa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
35fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
35fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
35fd0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
35fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35ff0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
36000 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
36020 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
36030 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36040 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
36050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
36060 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
36070 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
36080 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
36090 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
360a0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
360b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
360c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
360d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
360e0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
360f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
36100 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
36110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
36120 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36130 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
36140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36150 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
36160 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
36170 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
36180 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
36190 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
361a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
361b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
361c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
361d0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
361e0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
361f0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
36200 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45  ent Object.** DE
36210 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
36220 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
36230 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36240 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
36250 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
36260 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
36270 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
36280 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36290 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
362a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
362b0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
362c0 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
362d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
362e0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
362f0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
36300 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
36310 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
36320 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
36330 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
36340 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
36350 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
36360 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36370 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
36380 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
36390 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
363a0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
363b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
363c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
363d0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
363e0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
363f0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
36400 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
36410 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
36420 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
36430 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
36440 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
36450 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
36460 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
36470 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
36480 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
36490 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
364a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
364b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
364c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
364d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
364e0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
364f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
36500 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
36510 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
36520 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
36530 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
36540 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
36550 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
36560 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
36570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
36580 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
36590 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
365a0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
365b0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
365c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
365d0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
365e0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
365f0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
36600 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
36610 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
36620 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36630 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36640 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36650 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
36660 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
36670 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
36680 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
36690 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
366a0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
366b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
366c0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
366d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
366e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
366f0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
36700 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
36710 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36720 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
36730 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
36740 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36750 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
36760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36770 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
36780 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
36790 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
367a0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
367b0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
367c0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
367d0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
367e0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
367f0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
36800 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
36810 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
36820 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
36830 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
36840 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
36850 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
36860 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
36870 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
36880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36890 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
368a0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
368b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
368c0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
368d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
368e0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
368f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36900 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
36910 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
36920 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
36930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
36940 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
36950 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
36960 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
36970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
36980 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
36990 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
369a0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
369b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
369c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
369d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
369e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
369f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36a00 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
36a10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
36a20 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
36a30 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
36a40 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
36a50 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
36a60 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
36a70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
36a80 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
36a90 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
36aa0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
36ab0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
36ac0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
36ad0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
36ae0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
36af0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36b00 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
36b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
36b20 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
36b30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36b40 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
36b50 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
36b60 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
36b70 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
36b80 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
36b90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
36ba0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36bb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
36bc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
36bd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36be0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
36bf0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36c00 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
36c10 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
36c20 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
36c30 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
36c40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
36c50 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
36c60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
36c70 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
36c80 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
36c90 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
36ca0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
36cb0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
36cc0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
36cd0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
36ce0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
36cf0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
36d00 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
36d10 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
36d20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
36d30 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
36d40 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
36d50 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
36d60 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
36d70 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
36d80 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
36d90 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
36da0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
36db0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
36dc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
36dd0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
36de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
36df0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
36e00 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
36e10 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
36e20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
36e30 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
36e40 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
36e50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
36e60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36e70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
36e80 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
36e90 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
36ea0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
36eb0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
36ec0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
36ed0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
36ee0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
36ef0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
36f00 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
36f10 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
36f20 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
36f30 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
36f40 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
36f50 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
36f60 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
36f70 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
36f80 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
36f90 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
36fa0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
36fb0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
36fc0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
36fd0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
36fe0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
36ff0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
37000 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
37010 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
37020 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
37030 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
37040 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37050 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
37060 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
37070 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
37080 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
37090 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
370a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
370b0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
370c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
370d0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
370e0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
370f0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
37100 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
37110 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
37120 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
37130 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
37140 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
37150 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
37160 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
37170 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
37180 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
37190 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
371a0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
371b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
371c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
371d0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
371e0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
371f0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
37200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
37210 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
37220 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
37230 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
37240 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
37250 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
37260 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
37270 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
37280 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
37290 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
372a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
372b0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
372c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
372d0 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
372e0 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
372f0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
37300 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37310 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
37320 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37330 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
37340 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
37350 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
37360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37370 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
37380 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
37390 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
373a0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
373b0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
373c0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
373d0 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
373e0 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
373f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
37400 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
37410 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37420 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
37430 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
37440 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
37450 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
37460 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
37470 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
37480 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
37490 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
374a0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
374b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
374c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
374d0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
374e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
374f0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
37500 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
37510 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
37520 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
37530 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
37540 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37550 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
37560 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
37570 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
37580 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
37590 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
375a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
375b0 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
375c0 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
375d0 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
375e0 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
375f0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
37600 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
37610 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
37620 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
37630 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
37640 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
37650 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
37660 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
37670 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
37680 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
37690 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
376a0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
376b0 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
376c0 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
376d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
376e0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
376f0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
37700 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
37710 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
37720 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
37730 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
37740 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
37750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
37760 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
37770 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
37780 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
37790 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
377a0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
377b0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
377c0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
377d0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
377e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
377f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37800 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
37810 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
37820 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37830 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37840 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
37850 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
37860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
37870 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
37880 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
37890 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
378a0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
378b0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
378c0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
378d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
378e0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
378f0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
37900 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
37910 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
37920 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
37930 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
37940 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
37950 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
37960 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
37970 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
37980 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
37990 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
379a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
379b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
379c0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
379d0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
379e0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
379f0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
37a00 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
37a10 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
37a20 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
37a30 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
37a40 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
37a50 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
37a60 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
37a70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
37a80 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
37a90 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
37aa0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
37ab0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
37ac0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
37ad0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37ae0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
37af0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
37b00 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
37b10 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
37b20 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
37b30 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
37b40 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
37b50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
37b60 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
37b70 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
37b80 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
37b90 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
37ba0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37bb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37bc0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
37bd0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
37be0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
37bf0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37c00 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
37c10 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
37c20 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
37c30 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
37c40 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
37c50 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
37c60 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
37c70 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
37c80 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
37c90 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
37ca0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37cb0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
37cc0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
37cd0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
37ce0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
37cf0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
37d00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
37d10 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
37d20 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
37d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
37d40 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
37d50 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
37d60 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
37d70 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
37d80 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
37d90 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
37da0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
37db0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
37dc0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
37dd0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
37de0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
37df0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
37e00 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
37e10 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
37e20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
37e30 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
37e40 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
37e50 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
37e60 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
37e70 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
37e80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
37e90 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
37ea0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
37eb0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
37ec0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
37ed0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
37ee0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
37ef0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
37f00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37f10 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
37f20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
37f30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37f40 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
37f50 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
37f60 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
37f70 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
37f80 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
37f90 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
37fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37fb0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
37fc0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
37fd0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
37fe0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
37ff0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
38000 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
38010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38020 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
38030 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
38040 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
38050 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
38060 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
38070 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
38080 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
38090 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
380a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
380b0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
380c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
380d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
380e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
380f0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
38100 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
38110 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
38120 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
38130 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
38140 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
38150 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
38160 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
38170 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
38180 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
38190 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
381a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
381b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
381c0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
381d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
381e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
381f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
38200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38210 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
38220 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38230 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
38240 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
38250 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
38260 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
38270 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
38280 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
38290 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
382a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
382b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
382c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
382d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
382e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
382f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
38300 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
38310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
38320 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
38330 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
38340 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
38350 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
38360 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
38370 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
38380 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
38390 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
383a0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
383b0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
383c0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
383d0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
383e0 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
383f0 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
38400 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
38410 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
38420 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
38430 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
38440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38450 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
38460 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
38470 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
38480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
38490 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
384a0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
384b0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
384c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
384d0 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
384e0 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
384f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38500 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
38510 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
38520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
38530 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
38540 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
38550 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
38560 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
38570 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
38580 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
38590 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
385a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
385b0 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
385c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
385d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
385e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
385f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
38600 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
38610 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
38620 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
38630 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
38640 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
38650 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
38660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38670 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
38680 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
38690 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
386a0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
386b0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
386c0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
386d0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
386e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
386f0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
38700 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
38710 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
38720 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
38730 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
38740 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
38750 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
38760 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f t