/ Hex Artifact Content
Login

Artifact c442fca3fbabbc44b811218118fada3b63419a75974b50b82e9fd2fd5a49fda1:


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 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (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 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (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 57 52 49 54 45 20  ITE_IOERR_WRITE 
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 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<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 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<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 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
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 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
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 37 3c 3c 38 29 29 0a  IOERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
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 38 3c 3c 38 29 29 0a 23  OERR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
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 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<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 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
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 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
66c0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
66d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
66e0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
66f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6700: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6710: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6720: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6730: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6740: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6760: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
6770: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
6780: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
6790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
67a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
67b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
67c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
67d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
67e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
67f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
68a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
68b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
68c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
68d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
68e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
68f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
69a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
69b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
69c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
69d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
69e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
69f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
6a60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a80: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
6a90: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6aa0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6ab0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6ac0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6ad0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6ae0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6af0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6b00: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6b10: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6b20: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6b30: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6b40: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
6b50: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
6b60: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
6b70: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
6b80: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
6b90: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6ba0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6bb0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6bc0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6bd0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6be0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6c00: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6c10: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6c20: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6c30: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6c40: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6c50: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6c60: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6c70: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6ca0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6cb0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e  eans that the un
6cc0: 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65  derlying.** file
6cd0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
6ce0: 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77  doing multiple w
6cf0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6d00: 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20  atomically when 
6d10: 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f  those.** write o
6d20: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72  perations are br
6d30: 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49  acketed by [SQLI
6d40: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
6d50: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64  TOMIC_WRITE] and
6d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
6d70: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
6d80: 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69  WRITE]..*/.#defi
6d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6dc0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6df0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6e60: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e80: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6e90: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6eb0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ed0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ee0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6ef0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6f00: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f20: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6f50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6f60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6f70: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6fe0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
7000: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
7010: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
7020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7030: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
7040: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7050: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
7070: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
7080: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
7090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20  P_BATCH_ATOMIC  
70b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34           0x00004
70c0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
70d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
70e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
70f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
7100: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
7110: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7120: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
7130: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
7140: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
7150: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7160: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
7170: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7180: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
71b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
71c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
71d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
71e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
71f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7210: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
7220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7230: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
7240: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7250: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
7260: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
7270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
7280: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
7290: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
72a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
72b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
72d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
72e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
72f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7300: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
7310: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
7320: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7330: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
7340: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
7350: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
7360: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
7370: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
7380: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
7390: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
73a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
73b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
73c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
73d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
73e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
73f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7400: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7410: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7420: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7430: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7440: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7450: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7460: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7470: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7480: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
7490: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
74a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
74b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
74c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
74e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
74f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7500: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7520: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7530: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7540: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7550: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7560: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7570: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7580: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
7590: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
75a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
75b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
75c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
75d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
75e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
75f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7600: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7610: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7620: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7630: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7640: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7650: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7660: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7670: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7680: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
7690: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
76a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
76b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
76c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
76d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
76e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
76f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7700: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7710: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7720: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7730: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7740: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7750: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7770: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7780: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
77a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
77d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
77e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
77f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7800: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7810: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7830: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7840: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7850: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7860: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7870: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7880: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
7890: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
78a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
78b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
78c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
78d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
78e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
78f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7900: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7910: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7930: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7940: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7950: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7960: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7970: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7980: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
7990: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
79a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
79b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
79d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
79e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
79f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7a00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7a20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7a40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7a50: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7a60: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7a70: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a80: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
7a90: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7aa0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7ab0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7ac0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7ad0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7ae0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7af0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7b10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7b20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7b30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7b40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7b50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7b60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7b70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7b80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
7b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7ba0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7bb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7bd0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7be0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7bf0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7c00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7c10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7c20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7c30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7c40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7c50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7c60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7c70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7c80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
7c90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7ca0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7cb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7cc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7cd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7ce0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7cf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7d00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7d10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7d20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7d40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7d50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7d60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7d70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7d80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
7d90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7da0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7db0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7dc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7dd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7de0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7df0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7e00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7e10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7e30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7e40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7e50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7e60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7e70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7e80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7e90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ea0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7eb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ec0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ed0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7ee0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ef0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7f10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7f30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7f50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7f60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7f70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7f80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7f90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7fa0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7fb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7fc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7fe0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7ff0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
8000: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
8010: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
8020: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
8030: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
8040: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
8050: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
8060: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
8070: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
8080: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
8090: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
80a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
80b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
80c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
80d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
80e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
80f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
8100: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
8110: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
8120: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
8130: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8140: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
8150: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
8160: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
8170: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
8180: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
8190: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
81a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
81b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
81c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
81d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
81e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
81f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
8200: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
8210: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
8220: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
8230: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
8240: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
8250: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
8260: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
8270: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
8280: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
8290: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
82a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
82b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
82c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
82d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
82e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
82f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
8300: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
8310: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
8320: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
8330: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
8340: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
8350: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8360: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
8370: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8380: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8390: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
83a0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
83b0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
83c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
83d0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
83e0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
83f0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8400: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8410: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8420: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8430: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8440: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8450: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8460: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8470: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8480: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8490: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
84a0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
84b0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
84c0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
84d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
84e0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
84f0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8500: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8510: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8520: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8530: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8540: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8550: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8560: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8570: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8580: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8590: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
85a0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
85b0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
85c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8610: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8630: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8640: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8650: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8660: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8670: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8690: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
86a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8700: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8710: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8720: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8740: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8750: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8770: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
87a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
87b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
87c0: 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IC].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
9050: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
9060: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
9070: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9080: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
9090: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
90a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
90b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
90c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
90d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
90e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
90f0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
9100: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9110: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
9120: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9180: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9190: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
91a0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
91b0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
91c0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
91d0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
91e0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
91f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
9200: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
9210: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
9220: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
9230: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
9240: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
9250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
9260: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
9270: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
9280: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
9290: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
92a0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
92b0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
92c0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
92d0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
92e0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
92f0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9300: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9320: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9330: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9340: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9350: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9360: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9370: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
9380: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
9390: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93a0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93b0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
93c0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
93d0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
93e0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
93f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9400: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9410: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9420: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9430: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9440: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9450: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9460: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9470: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
9480: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
9490: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94b0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
94c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
94e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
94f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9510: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9520: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9530: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9540: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9550: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9560: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9570: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9580: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9590: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95b0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
95c0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
95d0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
95e0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
95f0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9600: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9610: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9620: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9630: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9640: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9650: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9660: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9670: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9680: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9690: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96a0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96b0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
96c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96d0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
96e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
96f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9700: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9710: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9720: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9740: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9750: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9760: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9770: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9780: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9790: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
97a0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
97c0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
97d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
97e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9800: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9810: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9830: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9840: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9850: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9860: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9870: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9880: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9890: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
98e0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
98f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9900: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9910: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9920: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9950: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9960: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9980: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9990: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
99a0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
99b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
99c0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
99d0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
99e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
99f0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9a00: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9a10: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9a20: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9a30: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9a40: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9a50: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9a60: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9a70: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9a80: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9a90: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9aa0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9ab0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9ac0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9ad0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9ae0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9af0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9b00: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9b10: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9b20: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9b30: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9b40: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9b60: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9b70: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9b80: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9b90: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ba0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9bb0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9bc0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9bd0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9be0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9bf0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9c00: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9c10: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c30: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9c40: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9c50: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9c60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9c70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9c80: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9c90: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9ca0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9cc0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9ce0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9cf0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9d00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9d10: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9d20: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9d30: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9d40: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9d50: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9d60: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9d70: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9d80: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9d90: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9da0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9db0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9dc0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9dd0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9df0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9e00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e10: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9e20: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9e30: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9e40: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9e50: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9e60: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9e70: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ea0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9eb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9ec0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9ed0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9ee0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9ef0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9f00: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9f10: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9f20: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9f30: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9f40: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9f50: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9f60: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9f70: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9f80: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9f90: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9fa0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9fb0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9fc0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9fd0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9fe0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9ff0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a000: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a010: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a020: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a030: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a040: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a050: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a060: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a070: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a080: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a090: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a0a0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a0b0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a0c0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a0d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a0e0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a0f0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a100: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a110: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a120: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a130: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a140: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a150: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a160: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a170: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a180: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a190: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a1a0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a1b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a1c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a1d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a1e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a1f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a200: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a210: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a220: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a230: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a240: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a250: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a260: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a270: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a280: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a290: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a2a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a2b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a2c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a2f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a310: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a320: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a330: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a340: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a350: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a360: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a370: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a380: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a390: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a3a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a3c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a3d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a3e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a3f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a400: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a410: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a420: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a430: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a440: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a450: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a460: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a470: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a480: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a490: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a4a0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a4b0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a4c0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a4d0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a4e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a4f0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a500: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a510: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a520: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a530: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a540: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a550: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a560: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a570: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a580: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a5a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a5b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a5c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a5d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a5e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a5f0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a600: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a610: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a620: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a630: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a640: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a650: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a660: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a670: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a680: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6a0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a6b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a6c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a6d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a6e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a6f0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a700: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a710: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a720: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a730: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a740: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a750: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a760: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a770: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a780: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a790: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a7a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a7b0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a7c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a7e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a7f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a800: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a810: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a820: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a830: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a840: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a850: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a860: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a870: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a880: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a890: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a8a0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a8b0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a8c0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a8d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8e0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a8f0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a910: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a920: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a930: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a940: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a950: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a960: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a970: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a980: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a990: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a9a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9b0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a9c0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a9d0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a9e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a9f0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aa00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aa10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa20: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
aa30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa40: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
aa50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
aa60: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
aa70: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
aa80: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
aa90: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
aaa0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
aab0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
aac0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
aad0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
aae0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aaf0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
ab00: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ab10: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
ab20: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
ab30: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
ab40: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
ab50: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
ab60: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
ab70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
ab80: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
ab90: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
aba0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
abb0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
abc0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
abd0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
abe0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
abf0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
ac00: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
ac10: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
ac20: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
ac30: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
ac40: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
ac50: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
ac60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
ac70: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
ac80: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
ac90: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
aca0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
acb0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
acc0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
acd0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
acf0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
ad00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ad10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
ad20: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
ad30: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ad40: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
ad50: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
ad60: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
ad70: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
ad80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
ad90: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
ada0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
adb0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
adc0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
add0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ade0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
adf0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ae00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ae10: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ae20: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ae30: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ae40: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ae50: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ae60: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ae70: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
ae80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aea0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aeb0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aec0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aee0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aef0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
af00: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
af10: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
af20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
af30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
af40: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
af50: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
af60: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
af70: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
af80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afa0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
afb0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
afc0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
afd0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
afe0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
aff0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b010: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b020: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b030: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b040: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b050: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b060: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b070: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b080: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b0a0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b0b0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b0c0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b0d0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b0e0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b0f0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b100: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b110: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b120: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b130: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b140: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b160: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b170: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b180: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b190: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b1a0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b1b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b1d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b1e0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b1f0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b200: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b210: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b230: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b240: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b250: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b260: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b270: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b280: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b290: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b2a0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b2b0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b2c0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b2d0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b2e0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b2f0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b300: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b310: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b320: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b330: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b340: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b360: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b370: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b380: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b390: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b3a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b3b0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b3c0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b3d0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b3e0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b3f0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b400: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b410: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b420: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b430: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b450: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b460: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b470: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b480: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b490: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b4a0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b4b0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b4c0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b4d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b4e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b500: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b510: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b520: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b530: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b540: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b560: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b570: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b580: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b590: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b5a0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b5b0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b5c0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b5d0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b5e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b5f0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b600: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b610: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b620: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b630: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b640: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b650: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b660: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b670: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b680: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b690: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b6a0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b6b0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b6c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b6d0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b6e0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b6f0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b700: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b710: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b720: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b730: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b740: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b750: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b760: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b770: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b780: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b790: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b7a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b7b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b7c0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b7d0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b7f0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b800: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b810: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b820: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b830: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b840: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b850: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b860: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b870: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b880: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b890: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b8a0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b8b0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b8c0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b8d0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b8e0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b8f0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b900: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b910: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b920: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b930: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b940: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b950: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b960: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b970: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b980: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b9e0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b9f0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ba00: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ba10: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ba20: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ba30: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ba40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ba50: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
ba60: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
ba70: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
ba80: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ba90: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
baa0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bab0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bac0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bad0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bae0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
baf0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bb00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bb10: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bb20: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
bb30: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
bb40: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
bb50: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
bb60: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
bb70: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
bb80: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
bb90: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
bba0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
bbb0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
bbc0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
bbd0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
bbe0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
bbf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc00: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
bc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
bc30: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
bc40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
bc50: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
bc60: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
bc70: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
bc80: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
bc90: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
bca0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bcb0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
bcc0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
bcd0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
bce0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
bcf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
bd00: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
bd10: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
bd20: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
bd30: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
bd40: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
bd50: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
bd70: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
bd80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bd90: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bdc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bdd0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bdf0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
be00: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
be10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
be20: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
be30: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
be40: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
be50: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
be60: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
be70: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
be80: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
be90: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bea0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
beb0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bee0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf00: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bf10: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bf20: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bf30: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bf40: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bf50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bf60: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bf70: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bf80: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf90: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bfa0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bfb0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bfc0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bfd0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bfe0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c000: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c010: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c030: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c040: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c050: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c060: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c070: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c080: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c090: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c0a0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c0b0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c0c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c0d0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c0e0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c0f0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c100: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c110: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c120: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c130: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c150: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c170: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c180: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c190: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c1a0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c1b0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c1c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c1d0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c1e0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c1f0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c200: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c210: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c220: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c230: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c240: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c250: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c260: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c270: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c290: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c2a0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c2b0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c2c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c2d0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c2f0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c300: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c310: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c320: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c330: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c340: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c350: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c390: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c3a0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c3b0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c3c0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c3d0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c3e0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c3f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c400: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c410: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c420: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c440: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c450: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c470: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c480: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c490: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c4a0: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c4b0: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c4c0: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c4d0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c4e0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c4f0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c500: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c510: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c520: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
c530: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
c540: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c550: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
c560: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
c570: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
c580: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
c590: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
c5a0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
c5b0: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
c5c0: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
c5d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c5e0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
c5f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
c600: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
c610: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c620: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
c640: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
c650: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
c660: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
c670: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
c680: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
c690: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
c6a0: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
c6b0: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
c6c0: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
c6d0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
c6e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
c6f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
c700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
c710: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c720: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
c740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c750: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c760: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
c770: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
c780: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
c790: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
c7a0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
c7b0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
c7c0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c7d0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
c7e0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
c7f0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
c810: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
c820: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c830: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
c840: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
c850: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
c860: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
c870: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
c880: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
c890: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
c8a0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
c8b0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
c8c0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c8d0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
c8e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
c8f0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
c900: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
c910: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
c920: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
c930: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
c940: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
c950: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
c960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c970: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
c980: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
c990: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
c9a0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
c9b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c9c0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
c9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c9e0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c9f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ca00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
ca10: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
ca20: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
ca30: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
ca40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
ca50: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
ca60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ca70: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
ca80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ca90: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
caa0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cab0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cac0: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cad0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cae0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
caf0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cb00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cb10: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cb20: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
cb30: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
cb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
cb50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
cb70: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
cb80: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
cb90: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
cba0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cbb0: 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  WRITE]..** </ul>
cbc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
cbe0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cbf0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
cc10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
cc20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cc30: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
cc40: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
cc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc60: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
cc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
cc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cc90: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
cca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
ccb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ccc0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ccd0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
cce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ccf0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
cd00: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
cd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cd20: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
cd30: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
cd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cd50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
cd60: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
cd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd80: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
cd90: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
cda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
cdb0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
cdc0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
cdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
cde0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
cdf0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ce10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ce20: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ce40: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
ce50: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ce70: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ce80: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ce90: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
cea0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ceb0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
cec0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
ced0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
cee0: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
cef0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cf10: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cf20: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
cf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
cf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf50: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
cf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf80: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
cf90: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
cfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfb0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
cfc0: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
cfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
cff0: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
d000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d010: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
d020: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
d030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d040: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
d050: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
d060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d070: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
d080: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
d090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
d0a0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
d0b0: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
d0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
d0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
d0e0: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
d100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d110: 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53      30.#define S
d120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d130: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  N_ATOMIC_WRITE  
d140: 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51     31.#define SQ
d150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d160: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  T_ATOMIC_WRITE  
d170: 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
d180: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
d190: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  CK_ATOMIC_WRITE 
d1a0: 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   33../* deprecat
d1b0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
d1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
d1d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d1e0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
d1f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d210: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d220: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d230: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
d240: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d250: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
d260: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
d270: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d280: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
d290: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
d2a0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
d2b0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
d2c0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
d2d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d2e0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
d2f0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
d300: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
d310: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
d320: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
d330: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
d340: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
d350: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
d360: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
d370: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
d380: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
d390: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
d3a0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
d3b0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
d3c0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
d3d0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
d3e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d3f0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
d400: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
d410: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
d420: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
d430: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
d440: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
d450: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
d460: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
d470: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
d480: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d490: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
d4a0: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
d4b0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
d4c0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
d4d0: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
d4e0: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
d4f0: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
d500: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
d510: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
d520: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
d530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
d540: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
d550: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d560: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d570: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
d580: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
d590: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d5a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d5b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d5c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d5d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
d5e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
d5f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
d600: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
d610: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
d620: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
d630: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
d640: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d650: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
d660: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
d670: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
d680: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
d690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
d6a0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
d6b0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
d6c0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
d6d0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
d6e0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
d6f0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
d700: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
d710: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
d720: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
d730: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
d740: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
d750: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
d760: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
d770: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d780: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
d790: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
d7a0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
d7b0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
d7c0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
d7d0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
d7e0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
d7f0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
d800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
d810: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
d820: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
d830: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
d840: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
d850: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
d860: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
d870: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
d880: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
d890: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
d8a0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
d8b0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
d8c0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
d8d0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
d8e0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
d8f0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
d900: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
d910: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
d920: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
d930: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
d940: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
d950: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
d960: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
d970: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
d980: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
d990: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
d9a0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
d9b0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
d9c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
d9d0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
d9e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
d9f0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
da00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
da10: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
da20: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
da30: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
da40: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
da50: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
da60: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
da70: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
da80: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
da90: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
daa0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
dab0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
dac0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
dad0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
dae0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
daf0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
db00: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
db10: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
db20: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
db30: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
db40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
db50: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
db60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
db70: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
db80: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
db90: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
dba0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
dbb0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
dbc0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
dbd0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
dbe0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
dbf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
dc00: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
dc10: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
dc20: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
dc30: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
dc40: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
dc50: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
dc60: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
dc70: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
dc80: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
dc90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
dca0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
dcb0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
dcc0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
dcd0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
dce0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
dcf0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
dd00: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
dd10: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
dd20: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
dd30: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
dd40: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
dd50: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
dd60: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
dd70: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
dd80: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
dd90: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
dda0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ddb0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ddc0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ddd0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
dde0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ddf0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
de00: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
de10: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
de20: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
de30: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
de40: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
de50: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
de60: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
de70: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
de80: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
de90: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
dea0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
deb0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
dec0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
ded0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
dee0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
def0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
df00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
df10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
df20: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
df30: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
df40: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
df50: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
df60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
df70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
df80: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
df90: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
dfa0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
dfb0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
dfc0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
dfd0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
dfe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
dff0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
e000: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e010: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
e020: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
e030: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
e040: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
e050: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
e060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e070: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
e080: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
e090: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
e0a0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
e0b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e0c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e0d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e0e0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
e0f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
e100: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
e110: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e120: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e130: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
e140: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e150: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
e160: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e170: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
e180: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e190: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
e1a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
e1c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
e1d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
e1e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
e1f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e200: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
e210: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e220: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
e230: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
e240: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
e250: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
e260: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
e270: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
e280: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
e290: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
e2a0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
e2b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e2c0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
e2d0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
e2e0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
e2f0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
e300: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
e310: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
e320: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
e330: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
e340: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
e350: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
e360: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
e370: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
e380: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
e390: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
e3a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e3b0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
e3c0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
e3d0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
e3e0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
e3f0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
e400: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
e410: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
e420: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
e430: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
e440: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
e450: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
e460: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e470: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e480: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
e490: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e4a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e4b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e4c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
e4d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e4e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
e4f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e500: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e510: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
e520: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e530: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
e540: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
e550: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e560: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e570: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
e580: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
e590: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
e5a0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
e5b0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
e5c0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
e5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
e5e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e5f0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
e600: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
e610: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
e620: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e630: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
e640: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
e650: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
e660: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
e670: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
e680: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
e690: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
e6a0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
e6b0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
e6c0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
e6d0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
e6e0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
e6f0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
e700: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
e710: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
e720: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
e730: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
e740: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
e750: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
e760: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
e770: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
e780: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
e790: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
e7a0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
e7b0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
e7c0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
e7d0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
e7e0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
e7f0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
e800: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
e810: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
e820: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
e830: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
e840: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
e850: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
e860: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
e870: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
e880: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
e890: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
e8a0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
e8b0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
e8c0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
e8d0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
e8e0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
e8f0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
e900: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
e910: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
e920: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
e930: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
e940: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
e950: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
e960: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
e970: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
e980: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
e990: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
e9a0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
e9b0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
e9c0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
e9d0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
e9e0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
e9f0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
ea00: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
ea10: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
ea20: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ea30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
ea40: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
ea50: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
ea60: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
ea70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ea80: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
ea90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
eaa0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
eab0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
eac0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ead0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
eae0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
eaf0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
eb00: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
eb10: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
eb20: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
eb30: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
eb40: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
eb50: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
eb60: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
eb70: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
eb80: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
eb90: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
eba0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
ebb0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
ebc0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
ebd0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
ebe0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
ebf0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
ec00: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
ec10: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
ec20: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
ec30: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
ec40: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
ec50: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
ec60: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
ec70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
ec80: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
ec90: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
eca0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
ecb0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
ecc0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
ecd0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
ece0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
ecf0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
ed00: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
ed10: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ed20: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
ed30: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
ed40: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
ed50: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
ed60: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
ed70: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
ed80: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
ed90: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
eda0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
edb0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
edc0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
edd0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ede0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
edf0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ee00: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ee10: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
ee20: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
ee30: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
ee40: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
ee50: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
ee60: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
ee70: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
ee80: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ee90: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
eea0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
eeb0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
eec0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
eed0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
eee0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
eef0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ef00: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ef10: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ef20: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ef30: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ef40: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ef50: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
ef60: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
ef70: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
ef80: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
ef90: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
efa0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
efb0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
efc0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
efd0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
efe0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
eff0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f000: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
f010: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
f020: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
f030: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
f040: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
f050: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
f060: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
f070: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f080: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
f090: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
f0a0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
f0b0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
f0c0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
f0d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
f0e0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
f0f0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
f100: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
f110: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
f120: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
f130: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
f140: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
f150: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
f160: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
f170: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
f180: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
f190: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
f1a0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
f1b0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
f1c0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
f1d0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
f1e0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
f1f0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
f200: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
f210: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
f220: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
f230: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
f240: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
f250: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
f260: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
f270: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
f280: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
f290: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
f2a0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
f2b0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
f2c0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
f2d0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
f2e0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
f2f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
f300: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
f310: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
f320: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
f330: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
f340: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
f350: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
f360: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
f370: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
f380: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
f390: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
f3a0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
f3b0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
f3c0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
f3d0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
f3e0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
f3f0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
f400: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
f410: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f420: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
f430: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
f440: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f450: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
f460: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
f470: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
f480: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f490: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
f4a0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
f4b0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
f4c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
f4d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
f4e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
f4f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
f500: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
f510: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
f520: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
f530: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
f540: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
f550: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
f560: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
f570: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f580: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
f590: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
f5a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
f5b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
f5d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
f5e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
f5f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
f600: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
f610: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f620: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
f630: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
f640: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
f650: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
f660: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
f670: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f680: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f690: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
f6a0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
f6b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f6c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f6d0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
f6e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
f6f0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
f700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f720: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
f730: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
f740: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
f750: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f760: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
f770: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
f780: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
f790: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
f7a0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
f7b0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
f7c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
f7d0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
f7e0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
f7f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
f800: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
f810: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
f820: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
f830: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
f840: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
f850: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
f860: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
f870: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
f880: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
f890: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
f8a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
f8b0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
f8c0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
f8d0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
f8e0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
f8f0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
f900: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f910: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
f920: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
f930: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
f940: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
f950: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
f960: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
f970: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
f980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f990: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
f9a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
f9b0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
f9c0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
f9d0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
f9e0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
f9f0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fa00: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
fa10: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
fa20: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
fa30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
fa40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fa50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
fa70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fa80: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
fa90: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
faa0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fab0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fac0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fad0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
fae0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
faf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fb00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
fb10: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fb20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fb30: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
fb40: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
fb50: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
fb60: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
fb70: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
fb80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
fb90: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
fba0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
fbb0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
fbc0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
fbd0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
fbe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fbf0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
fc00: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
fc10: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
fc20: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
fc30: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
fc40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
fc50: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
fc60: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
fc70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
fc80: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
fc90: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
fca0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
fcb0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
fcc0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
fcd0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
fce0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
fcf0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
fd00: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
fd10: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
fd20: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
fd30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
fd40: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
fd50: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fd60: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fd70: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
fd80: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
fd90: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
fda0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
fdc0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
fdd0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
fde0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
fdf0: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
fe00: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
fe10: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
fe20: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
fe30: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
fe40: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
fe50: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
fe60: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
fe70: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
fe80: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
fe90: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
fea0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
feb0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fec0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fed0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fee0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
fef0: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ff00: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ff10: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ff20: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
ff30: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
ff40: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
ff50: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
ff60: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
ff70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ff80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
ff90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
ffa0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ffb0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
ffc0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
ffd0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ffe0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fff0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10000 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10010 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10020 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10030 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10040 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10050 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10060 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10070 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10080 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10090 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
100a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
100b0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
100c0 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
100d0 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
100e0 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
100f0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10100 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10110 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10120 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10130 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10140 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10150 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10160 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10170 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10180 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10190 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
101a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
101b0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
101c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
101d0 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
101e0 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
101f0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10200 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10210 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10220 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10230 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10240 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10250 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10260 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10270 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10280 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10290 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
102a0 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
102b0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
102c0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
102d0 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
102e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
102f0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10300 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10310 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10320 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10330 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10340 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
10350 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10360 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
10370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10380 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
10390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103a0 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
103b0 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
103c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
103d0 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
103e0 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
103f0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
10400 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
10410 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
10420 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
10430 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
10440 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
10450 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
10460 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
10470 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
10480 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
10490 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
104a0 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
104b0 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
104c0 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
104d0 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
104e0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
104f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10500 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10510 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
10520 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
10530 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
10540 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
10550 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
10560 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
10570 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
10580 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
10590 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
105a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
105b0 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
105c0 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
105d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
105e0 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
105f0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
10600 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
10610 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
10620 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
10630 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
10640 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
10650 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
10660 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
10670 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
10680 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
10690 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
106a0 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
106b0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
106c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
106e0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
106f0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
10700 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
10710 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10720 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10730 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
10740 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
10750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10760 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
10770 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10780 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
10790 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
107a0 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
107b0 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
107c0 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
107d0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
107e0 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
107f0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10800 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
10810 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
10820 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
10830 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
10840 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
10850 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
10860 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10870 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
10880 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
10890 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
108a0 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
108b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
108c0 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
108d0 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
108e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
108f0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10900 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
10910 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10920 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
10930 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
10940 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
10950 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
10960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
10970 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
10980 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
10990 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
109a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
109b0 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
109c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
109d0 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
109e0 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
109f0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
10a00 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
10a10 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
10a20 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
10a30 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
10a40 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
10a50 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
10a60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
10a70 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
10a80 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10a90 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
10aa0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
10ab0 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
10ac0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10ae0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10b00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10b10 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10b20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10b30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10b40 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10b50 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10b60 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10b70 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10b80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10b90 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10ba0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10bb0 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10bc0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10bd0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10be0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10bf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10c00 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
10c10 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
10c20 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
10c30 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
10c40 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
10c50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10c60 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10c70 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10c90 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10ca0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10cb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10cc0 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10cd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10ce0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10cf0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
10d00 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
10d10 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
10d20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
10d30 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
10d40 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
10d50 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10d60 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10d70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10d80 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10d90 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10da0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10db0 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10dc0 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10dd0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10de0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10df0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
10e00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
10e10 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
10e20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10e30 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
10e40 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10e50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10e60 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10e70 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10e80 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10e90 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10ea0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10eb0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10ec0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10ed0 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10ee0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10ef0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10f00 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
10f10 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
10f20 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
10f30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10f40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
10f50 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10f60 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10f70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10f80 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10f90 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10fa0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10fb0 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10fc0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10fd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10fe0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10ff0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11000 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11010 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11020 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11030 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11040 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11050 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11060 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11070 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11080 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11090 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
110a0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
110b0 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
110c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
110d0 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
110e0 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
110f0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11100 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11110 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11120 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11130 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11140 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11150 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11180 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
111a0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
111b0 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
111c0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
111d0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
111e0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
111f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11200 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11220 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11230 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11240 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11250 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11260 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11280 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11290 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
112a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
112b0 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
112c0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
112d0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
112e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
112f0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11300 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11310 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11320 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11330 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11340 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
11350 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
11360 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
11370 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
11380 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
11390 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
113a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
113b0 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
113c0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
113d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
113e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
113f0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
11400 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
11410 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
11420 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
11430 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
11440 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
11450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11460 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11470 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
11480 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
11490 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
114a0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
114b0 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
114c0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
114d0 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
114e0 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
114f0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
11500 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11510 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
11520 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
11530 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
11540 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
11550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11560 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
11570 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11580 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11590 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
115a0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
115b0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
115c0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
115d0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
115e0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
115f0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11600 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11610 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11620 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11640 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11650 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11660 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11670 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11680 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
11690 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
116a0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
116b0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
116c0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
116d0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
116e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
116f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11700 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
11710 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
11720 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
11730 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11740 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11750 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11760 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11770 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11780 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
11790 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
117a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
117b0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
117c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
117d0 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
117e0 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
117f0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
11800 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11810 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
11820 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
11830 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
11840 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
11850 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
11860 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
11870 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
11880 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
11890 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
118a0 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
118b0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
118c0 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
118d0 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
118e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
118f0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
11900 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
11910 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
11920 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
11930 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
11940 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
11950 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11960 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
11970 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
11980 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
11990 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
119a0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
119b0 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
119c0 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
119d0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
119e0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
119f0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
11a00 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
11a10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11a20 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
11a30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
11a40 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
11a50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a60 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
11a70 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11a80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11a90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11aa0 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11ab0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11ac0 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11ad0 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11ae0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11af0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11b00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
11b10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11b20 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
11b30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11b40 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
11b50 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11b60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11b70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11b80 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11b90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11ba0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11bb0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11bc0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11bd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11be0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11bf0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
11c00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
11c10 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
11c20 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
11c30 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
11c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11c50 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11c60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11c70 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11c80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11c90 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11ca0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11cb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11cc0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11cd0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11ce0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11cf0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
11d00 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
11d10 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
11d20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11d30 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
11d40 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
11d50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11d60 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11d70 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11d80 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11d90 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11da0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11db0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11dc0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11dd0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11de0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11df0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
11e00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11e10 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
11e20 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11e30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
11e40 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
11e50 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11e60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11e70 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11e80 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11e90 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11ea0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11eb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11ec0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11ed0 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11ee0 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11ef0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
11f00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
11f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
11f20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11f30 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
11f40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
11f50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11f60 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11f70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11f80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11f90 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11fb0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11fc0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11fd0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11fe0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11ff0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12000 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12010 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12020 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12030 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12040 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12050 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12060 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12080 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12090 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
120a0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
120b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
120c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
120d0 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
120e0 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
120f0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12100 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12110 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12120 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12130 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12140 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12150 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12160 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12170 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12180 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12190 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
121a0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
121b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121c0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
121d0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
121e0 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
121f0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12200 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12210 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12220 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12230 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12240 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12250 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12260 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12270 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12280 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12290 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
122a0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
122b0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
122c0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
122d0 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
122e0 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
122f0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12300 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12310 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12320 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12330 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12340 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12350 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
12360 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
12370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12380 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12390 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
123a0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
123b0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
123c0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
123d0 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
123e0 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
123f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12400 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12410 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
12420 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
12430 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
12440 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
12450 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
12460 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
12470 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12480 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12490 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
124a0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
124b0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
124c0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
124d0 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
124e0 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
124f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12500 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12510 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
12520 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12540 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
12550 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
12560 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
12570 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12580 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12590 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
125a0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
125b0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
125c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
125d0 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
125e0 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
125f0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12600 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12610 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12620 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12630 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12640 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12650 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12670 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12680 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12690 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
126a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
126b0 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
126c0 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
126d0 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
126e0 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
126f0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
12700 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
12710 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
12720 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
12730 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
12740 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
12750 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
12760 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
12770 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
12780 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
12790 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
127a0 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
127b0 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
127c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
127d0 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
127e0 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
127f0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
12800 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12810 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
12820 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
12830 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
12840 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
12850 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
12860 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
12870 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
12880 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
12890 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
128a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
128b0 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
128c0 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
128d0 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
128e0 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
128f0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
12900 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
12910 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12920 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
12930 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
12940 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12950 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12970 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
12980 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
12990 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
129a0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
129b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
129c0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
129d0 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
129e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
129f0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
12a00 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
12a10 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
12a20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
12a30 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
12a40 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
12a50 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
12a60 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
12a70 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12a80 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
12a90 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
12aa0 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
12ab0 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
12ac0 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
12ad0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12ae0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12af0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
12b00 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
12b10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12b20 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
12b30 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
12b40 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
12b50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12b60 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12b70 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12b80 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12b90 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12ba0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12bb0 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12bc0 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12bd0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12be0 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12bf0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12c00 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
12c10 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
12c20 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
12c30 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
12c40 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
12c50 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12c60 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12c70 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12c80 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12c90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12ca0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12cc0 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12cd0 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12ce0 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12cf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
12d00 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
12d10 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
12d20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
12d30 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
12d40 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
12d50 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12d60 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12d70 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12d80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12da0 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12db0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12dc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12dd0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12de0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12df0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
12e00 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
12e10 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
12e20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12e30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
12e40 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
12e50 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12e60 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12e70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12e80 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12e90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ea0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12eb0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12ec0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12ed0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12ee0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12f00 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
12f10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
12f20 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
12f30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12f40 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
12f50 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12f60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12f70 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12f80 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12f90 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12fa0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12fb0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12fc0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12fd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12fe0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12ff0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13000 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13010 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13020 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13030 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13040 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13050 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13060 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13070 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13080 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13090 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
130a0 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
130b0 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
130c0 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
130d0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
130e0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
130f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13100 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13110 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13120 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13130 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13140 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13150 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13160 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13170 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13180 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13190 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
131a0 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
131b0 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
131c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
131d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
131e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
131f0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13210 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13220 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13230 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13250 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13260 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13270 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13280 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13290 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
132a0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
132b0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
132c0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
132d0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
132e0 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
132f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13300 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13310 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13350 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13360 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
13370 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
13380 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
13390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133a0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
133b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
133c0 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
133d0 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
133e0 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
133f0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
13400 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
13410 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
13420 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
13430 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
13440 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
13450 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
13460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13470 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
13480 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
13490 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
134a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
134b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
134c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
134d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
134e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
134f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13500 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
13510 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
13520 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13540 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13550 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13560 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13570 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13580 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
135a0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
135b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
135c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
135d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
135e0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
135f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13600 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13610 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13620 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13630 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13640 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
13650 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
13660 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
13670 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
13680 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
13690 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
136a0 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
136b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
136c0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
136d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
136e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
136f0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
13700 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
13710 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13720 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13730 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13740 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
13750 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
13760 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
13770 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
13780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13790 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
137a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
137b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
137c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
137d0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
137e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
137f0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
13800 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
13810 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
13820 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
13830 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13840 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13850 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13860 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13870 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13880 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13890 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
138a0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
138b0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
138c0 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
138d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
138e0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
138f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13900 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13910 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13920 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13930 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13940 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
13950 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13960 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13980 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
139a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
139b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
139c0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
139d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
139e0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
139f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13a00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13a20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13a30 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13a40 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13a50 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13a60 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13a70 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13a80 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13a90 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
13aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13ab0 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
13ac0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13ad0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
13ae0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
13af0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
13b00 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13b10 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13b20 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
13b30 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
13b40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
13b50 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13b60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13b70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13b80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13b90 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13bb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13bc0 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13bd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13be0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13bf0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13c00 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
13c20 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13c30 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
13c40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13c50 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13c60 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13c70 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13c80 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13c90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13ca0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13cb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13cc0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13cd0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13ce0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13cf0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
13d00 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
13d10 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
13d20 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
13d30 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
13d40 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
13d50 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13d60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d70 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
13d80 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d90 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
13da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13db0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13dc0 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
13dd0 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
13de0 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
13df0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
13e00 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
13e10 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
13e20 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
13e30 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
13e40 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
13e50 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
13e60 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
13e70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
13e80 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
13e90 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
13ea0 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
13eb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ec0 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
13ed0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
13ee0 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
13ef0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
13f00 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
13f10 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
13f20 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
13f30 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
13f40 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
13f50 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
13f60 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
13f70 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
13f80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13f90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13fa0 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13fb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13fc0 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13fd0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13fe0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13ff0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14000 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14010 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14020 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14030 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14040 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14050 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14060 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14080 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
140a0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
140b0 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
140c0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
140d0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
140e0 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
140f0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14100 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14110 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14120 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14130 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14140 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14150 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14160 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14170 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14180 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14190 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
141a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
141b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
141c0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
141d0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
141e0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
141f0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14200 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14210 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14220 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14230 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14240 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14250 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14260 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14270 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14280 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14290 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
142a0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
142b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
142c0 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
142d0 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
142e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
142f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14300 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14310 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14320 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14330 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14340 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
14350 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14360 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
14370 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14380 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
14390 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
143a0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
143b0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
143c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
143d0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
143e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
143f0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
14400 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14410 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
14420 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14430 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
14440 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
14450 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
14460 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14470 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14480 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14490 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
144a0 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
144b0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
144c0 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
144d0 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
144e0 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
144f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
14500 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
14510 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
14520 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
14530 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
14540 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
14550 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
14560 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
14570 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
14580 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
14590 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
145a0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
145b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
145c0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
145d0 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
145e0 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
145f0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
14600 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14610 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
14620 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
14630 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14640 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14650 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
14660 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
14670 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
14680 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
14690 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
146a0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
146b0 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
146c0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
146d0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
146e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
146f0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
14700 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
14710 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14720 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
14730 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
14740 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
14750 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
14760 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
14770 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
14780 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
14790 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
147a0 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
147b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
147c0 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
147d0 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
147e0 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
147f0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
14800 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
14810 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
14820 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
14830 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
14840 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
14850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14860 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
14870 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
14880 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
14890 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
148a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
148b0 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
148c0 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
148d0 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
148e0 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
148f0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
14900 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
14910 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14920 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14930 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14940 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14950 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
14960 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
14970 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
14980 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14990 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
149a0 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
149b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
149c0 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
149d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
149e0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
149f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14a00 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
14a10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14a20 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
14a30 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
14a40 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
14a50 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
14a60 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
14a70 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
14a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14a90 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
14aa0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
14ab0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
14ac0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14ad0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14ae0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14af0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14b00 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14b10 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14b20 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14b30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14b40 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14b50 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14b60 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14b70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14b80 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
14b90 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14ba0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14bb0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14bc0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14bd0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14be0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14bf0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14c00 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14c10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
14c20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
14c30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
14c40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
14c50 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14c60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
14c70 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
14c80 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
14c90 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
14ca0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14cb0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
14cc0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
14cd0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
14ce0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14cf0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14d10 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
14d20 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
14d30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
14d40 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
14d50 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14d60 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
14d70 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
14d80 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
14d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14da0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14db0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14dc0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
14dd0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14de0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14df0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14e00 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14e10 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
14e20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
14e30 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14e40 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
14e50 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
14e60 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
14e70 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
14e80 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14e90 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
14ea0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
14eb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ec0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
14ed0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14ee0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14ef0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14f00 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14f10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14f20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14f30 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
14f40 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14f50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14f60 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14f70 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
14f80 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14f90 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
14fa0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
14fb0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
14fc0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
14fd0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
14fe0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14ff0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15000 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15010 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15020 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15030 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15040 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15050 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15070 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15080 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15090 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
150a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
150b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
150c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
150d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
150e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
150f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15100 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15110 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15120 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15140 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15170 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15180 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15190 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
151a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
151b0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
151c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
151d0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
151e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
151f0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15200 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15210 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15220 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15230 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15240 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15250 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15260 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15270 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15280 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15290 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
152a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
152b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
152c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
152d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
152e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
152f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15300 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15310 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15320 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15330 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15340 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
15350 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
15360 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
15370 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
15380 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
15390 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
153a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
153b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
153c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
153d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
153e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
153f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15400 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15410 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15420 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15430 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15440 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15450 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15460 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
15470 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15480 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15490 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
154a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
154b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
154c0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
154d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
154e0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
154f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15500 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
15510 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15520 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15530 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
15540 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
15550 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15560 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
15570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
15580 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15590 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
155a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
155b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
155c0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
155d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
155e0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
155f0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
15600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15610 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
15620 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
15630 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
15640 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
15650 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
15660 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15670 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
15680 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
15690 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
156a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
156b0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
156c0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
156d0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
156e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
156f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15710 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
15720 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
15730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15740 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15750 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
15760 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15770 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15780 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
15790 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
157a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
157b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
157c0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
157d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
157e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
157f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15800 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
15810 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15820 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15830 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15840 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
15850 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15860 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
15870 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15880 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
158a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
158b0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
158c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
158d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
158e0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
158f0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15900 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15910 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15920 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15930 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15940 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15950 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15960 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15980 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15990 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
159a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
159b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
159c0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
159d0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
159e0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
159f0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15a00 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15a10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15a20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15a30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15a40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15a50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15a60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15a70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15a80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15a90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15aa0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15ab0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15ac0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15ad0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15ae0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15af0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15b00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15b10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15b20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15b30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15b40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15b50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15b60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15b70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15b80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15b90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15ba0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15bb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15bc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15bd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15bf0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15c00 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15c10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15c20 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15c30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15c40 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15c50 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15c60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
15c70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15c80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
15c90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15ca0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
15cb0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
15cc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15cd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15ce0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15cf0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15d00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15d10 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15d20 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15d30 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15d40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15d50 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15d60 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
15d70 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15d80 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
15d90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
15da0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
15db0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15dc0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15dd0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15de0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15df0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15e00 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15e10 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15e20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15e30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15e40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15e60 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
15e70 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15e80 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
15e90 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
15ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15eb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15ec0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
15ed0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
15ee0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15ef0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
15f00 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15f10 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
15f20 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15f30 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
15f40 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
15f50 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15f60 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
15f70 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
15f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15f90 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
15fa0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
15fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15fc0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
15fd0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
15fe0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
15ff0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16000 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16010 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16020 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16030 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16040 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16050 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16060 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16070 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16080 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16090 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
160a0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
160b0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
160c0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
160d0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
160e0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
160f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16100 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16110 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16120 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16130 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16140 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16150 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16160 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16170 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16180 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16190 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
161a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
161b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
161c0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
161d0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
161e0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
161f0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16200 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16210 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16220 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16230 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16240 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16250 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16260 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16270 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16280 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16290 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
162a0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
162b0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
162c0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
162d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
162e0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
162f0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16300 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16310 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16320 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16330 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16340 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
16350 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16360 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
16370 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
16380 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
16390 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
163a0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
163b0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
163c0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
163d0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
163e0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
163f0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
16400 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
16410 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
16420 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
16430 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
16440 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
16450 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
16460 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
16470 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
16480 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
16490 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
164a0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
164b0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
164c0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
164d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
164e0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
164f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
16500 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16510 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
16520 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16530 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
16540 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
16550 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
16560 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
16570 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
16580 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
16590 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
165a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
165b0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
165c0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
165d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
165e0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
165f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16600 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
16610 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
16620 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16630 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
16640 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16650 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
16660 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
16670 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
16680 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
16690 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
166a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
166b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
166c0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
166d0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
166e0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
166f0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
16700 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
16710 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
16720 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
16730 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
16740 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
16750 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
16760 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
16770 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
16780 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
16790 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
167a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
167b0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
167c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
167d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
167e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
167f0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
16800 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
16810 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16820 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
16830 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
16840 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
16850 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
16860 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
16870 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16880 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
16890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
168a0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
168b0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
168c0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
168d0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
168e0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
168f0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16900 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16910 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16920 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16940 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16950 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16960 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16970 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16980 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16990 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
169a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
169b0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
169c0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
169d0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
169e0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
169f0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16a00 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16a10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16a20 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16a30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16a40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16a50 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16a60 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16a70 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16a80 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16a90 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16aa0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16ab0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16ac0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16ad0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16ae0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16af0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16b00 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16b10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16b20 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16b30 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16b40 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16b50 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16b60 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16b70 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16b80 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
16b90 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
16ba0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
16bb0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
16bc0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16bd0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16be0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16bf0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16c00 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16c10 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
16c20 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
16c30 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
16c40 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
16c50 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
16c60 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16c70 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
16c80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16c90 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
16ca0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
16cb0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
16cc0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
16cd0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
16ce0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16cf0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16d00 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16d10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16d20 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
16d30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16d40 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16d50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
16d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16d70 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
16d80 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16d90 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
16da0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
16db0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
16dc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
16dd0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
16de0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16df0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16e00 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16e10 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
16e20 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
16e30 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
16e40 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
16e50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
16e60 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
16e70 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16e90 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
16ea0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16eb0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
16ec0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16ed0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16ee0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16ef0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16f00 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16f10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
16f30 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
16f40 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
16f50 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
16f60 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
16f70 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
16f80 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
16f90 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16fa0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
16fb0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
16fc0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
16fd0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
16fe0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
16ff0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17000 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17010 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17030 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17040 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17050 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17060 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17070 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17080 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17090 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
170a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
170b0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
170c0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
170d0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
170e0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
170f0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17100 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17110 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17120 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17130 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17140 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17150 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17160 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17170 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17180 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17190 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
171a0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
171b0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
171c0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
171d0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
171e0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
171f0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17200 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17210 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17220 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17230 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17240 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17250 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17260 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17270 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17280 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17290 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
172a0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
172b0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
172c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
172d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
172e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
172f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17300 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17310 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17320 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17330 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17340 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
17350 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
17360 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
17370 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
17380 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
17390 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
173a0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
173b0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
173c0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
173d0 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
173e0 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
173f0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
17400 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
17410 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
17420 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
17430 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
17440 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
17450 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
17460 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
17470 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
17480 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
17490 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
174a0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
174b0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
174c0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
174d0 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
174e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
174f0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
17500 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
17510 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
17520 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
17530 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
17540 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
17550 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
17560 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17570 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
17580 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17590 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
175a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
175b0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
175c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
175d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
175e0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
175f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17600 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
17610 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
17620 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
17630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17640 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
17650 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
17660 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
17670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17680 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
17690 20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c        6  /* No l
176a0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
176b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
176c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
176d0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
176e0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
176f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17700 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
17710 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
17720 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
17730 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
17740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
17750 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
17760 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
17770 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17780 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
17790 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
177a0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
177b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
177c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
177d0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
177e0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
177f0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
17800 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
17810 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
17820 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
17830 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
17840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17850 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
17860 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
17870 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17880 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
17890 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
178a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
178b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
178c0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
178d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
178e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
178f0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
17900 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
17910 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17920 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
17930 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
17940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17950 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
17960 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
17970 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17980 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17990 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
179a0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
179b0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
179c0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
179d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
179e0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
179f0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
17a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a10 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
17a20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
17a30 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
17a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17a50 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
17a60 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
17a70 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
17a80 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
17a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17aa0 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
17ab0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
17ac0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
17ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17ae0 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
17af0 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
17b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b10 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20  _CONFIG_PMASZ   
17b20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
17b30 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  /* unsigned int 
17b40 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65  szPma */.#define
17b50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17b60 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20  TMTJRNL_SPILL   
17b70 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42     26  /* int nB
17b80 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
17b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
17ba0 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  LL_MALLOC       
17bb0 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20   27  /* boolean 
17bc0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17bd0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
17be0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
17bf0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
17c00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
17c10 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
17c20 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
17c30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17c40 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
17c50 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
17c60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17c70 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
17c80 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17c90 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
17ca0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
17cb0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
17cc0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
17cd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
17ce0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
17cf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17d00 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
17d10 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
17d20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
17d30 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
17d40 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
17d50 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17d60 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
17d70 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
17d80 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
17d90 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17da0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17db0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
17dc0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
17dd0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
17de0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
17df0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
17e00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
17e10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
17e20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
17e30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17e40 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17e50 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17e60 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
17e70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17e80 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
17e90 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
17ea0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
17eb0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
17ec0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
17ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ee0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
17ef0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
17f00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17f10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
17f20 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
17f30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
17f40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
17f50 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
17f60 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
17f70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17f80 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
17f90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17fa0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
17fb0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
17fc0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
17fd0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
17fe0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
17ff0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
18000 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
18010 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
18020 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18030 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
18040 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
18050 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
18060 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
18070 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
18080 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
18090 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
180a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
180b0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
180c0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
180d0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
180e0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
180f0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
18100 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
18110 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
18120 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
18130 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
18140 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
18150 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
18160 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18170 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
18180 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
18190 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
181a0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
181b0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
181c0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
181d0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
181e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
181f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
18200 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
18210 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
18220 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
18230 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
18240 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
18250 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
18260 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
18270 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
18280 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
18290 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
182a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
182b0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
182c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
182d0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
182e0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
182f0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
18300 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
18310 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
18320 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
18330 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
18340 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
18350 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
18360 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
18370 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
18380 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
18390 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
183a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
183b0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
183c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
183d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
183e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
183f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
18400 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
18410 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
18420 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18430 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18440 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
18460 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
18470 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18480 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18490 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
184a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
184b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
184c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
184d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
184e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
184f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18500 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18510 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18520 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18530 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18540 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
18550 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
18560 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
18570 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18580 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18590 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
185a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
185b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
185c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
185d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
185e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
185f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18600 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18610 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
18620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18630 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18640 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18650 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
18660 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
18670 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
18680 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18690 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
186a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
186b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
186c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
186d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
186e0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
186f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
18700 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
18710 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18720 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
18730 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18740 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18750 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18760 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18770 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18780 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18790 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
187a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
187b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
187c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
187d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
187e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
187f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18800 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18810 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
18820 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18830 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18840 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18850 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18860 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
18870 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18880 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18890 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
188a0 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
188b0 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
188c0 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
188d0 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
188e0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
188f0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
18900 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
18910 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
18920 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
18930 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18940 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18950 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18960 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18970 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18980 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
18990 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
189a0 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
189b0 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
189c0 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
189d0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
189e0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
189f0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
18a00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18a10 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18a20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18a30 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18a40 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18a50 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
18a60 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
18a70 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18a80 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18a90 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18aa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18ab0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18ac0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18ad0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
18ae0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
18af0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18b00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18b10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18b20 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
18b30 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSION</dt>.** <
18b40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18b50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18b60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18b70 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
18b80 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
18b90 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65  interface indepe
18ba0 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b  ndently of the [
18bb0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18bc0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  ] SQL function..
18bd0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
18be0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
18bf0 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61  nsion()] API ena
18c00 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
18c10 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41   both the.** C-A
18c20 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  PI [sqlite3_load
18c30 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e  _extension()] an
18c40 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18c50 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  on [load_extensi
18c60 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  on()]..** There 
18c70 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18c80 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18c90 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  ts..** When the 
18ca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18cb0 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
18cc0 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79   is 1, then only
18cd0 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a   the C-API is.**
18ce0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65   enabled and the
18cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
18d00 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20  mains disabled. 
18d10 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
18d20 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69  gument to.** thi
18d30 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30  s interface is 0
18d40 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20  , then both the 
18d50 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51  C-API and the SQ
18d60 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  L function are d
18d70 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74  isabled..** If t
18d80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18d90 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f  t is -1, then no
18da0 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64   changes are mad
18db0 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69  e to state of ei
18dc0 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50  ther the.** C-AP
18dd0 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e  I or the SQL fun
18de0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65  ction..** The se
18df0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18e00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18e10 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18e20 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18e30 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18e40 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73  icate whether [s
18e50 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18e60 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
18e70 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65  ce.** is disable
18e80 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c  d or enabled fol
18e90 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18ea0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18eb0 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62  rameter may.** b
18ec0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18ed0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
18ee0 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
18ef0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18f00 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  back..** </dd>.*
18f10 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18f20 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18f30 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  AME</dt>.** <dd>
18f40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18f50 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
18f60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18f70 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a  "main" database.
18f80 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65  ** schema.  ^The
18f90 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69   sole argument i
18fa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18fb0 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73   constant UTF8 s
18fc0 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77  tring.** which w
18fd0 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e  ill become the n
18fe0 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69  ew schema name i
18ff0 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e  n place of "main
19000 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64  ".  ^SQLite.** d
19010 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63  oes not make a c
19020 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d  opy of the new m
19030 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  ain schema name 
19040 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61  string, so the a
19050 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
19060 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
19070 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  he argument pass
19080 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43  ed into this DBC
19090 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20  ONFIG option is 
190a0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74  unchanged.** unt
190b0 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74  il after the dat
190c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
190d0 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64   closes..** </dd
190e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
190f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
19100 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74  KPT_ON_CLOSE</dt
19110 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c  >.** <dd> Usuall
19120 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  y, when a databa
19130 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69  se in wal mode i
19140 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61  s closed or deta
19150 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20  ched from a .** 
19160 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
19170 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69   SQLite checks i
19180 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e  f this will mean
19190 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
191a0 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65  now no .** conne
191b0 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f  ctions at all to
191c0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
191d0 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d  f so, it perform
191e0 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a  s a checkpoint .
191f0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66  ** operation bef
19200 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  ore closing the 
19210 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73  connection. This
19220 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
19230 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69  sed to.** overri
19240 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75  de this behaviou
19250 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72  r. The first par
19260 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
19270 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a   this operation.
19280 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
19290 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64   - non-zero to d
192a0 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e  isable checkpoin
192b0 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20  ts-on-close, or 
192c0 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66  zero (the.** def
192d0 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20  ault) to enable 
192e0 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64  them. The second
192f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19300 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19310 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68  teger.** into wh
19320 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
19330 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19340 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70  e whether checkp
19350 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a  oints-on-close.*
19360 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61  * have been disa
19370 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79  bled - 0 if they
19380 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65   are not disable
19390 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65  d, 1 if they are
193a0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64  ..** </dd>.** <d
193b0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
193c0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64  G_ENABLE_QPSG</d
193d0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  t>.** <dd>^(The 
193e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
193f0 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69  ENABLE_QPSG opti
19400 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
19410 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
19420 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65  he [query planne
19430 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72  r stability guar
19440 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20  antee] (QPSG).  
19450 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73  When the QPSG is
19460 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69   active,.** a si
19470 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73  ngle SQL query s
19480 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c  tatement will al
19490 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
194a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61  e algorithm rega
194b0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c  rdless.** of val
194c0 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  ues of [bound pa
194d0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65  rameters].)^ The
194e0 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73   QPSG disables s
194f0 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  ome query optimi
19500 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  zations.** that 
19510 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75  look at the valu
19520 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61  es of bound para
19530 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61  meters, which ca
19540 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72  n make some quer
19550 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20  ies.** slower.  
19560 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73  But the QPSG has
19570 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f   the advantage o
19580 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62  f more predictab
19590 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69  le behavior.  Wi
195a0 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61  th.** the QPSG a
195b0 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69  ctive, SQLite wi
195c0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
195d0 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61  e same query pla
195e0 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  n in the field a
195f0 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75  s.** was used du
19600 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20  ring testing in 
19610 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64  the lab..** </dd
19620 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
19630 44 42 43 4f 4e 46 49 47 5f 46 55 4c 4c 5f 45 51  DBCONFIG_FULL_EQ
19640 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42  P</dt>.** <dd> B
19650 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f  y default, the o
19660 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e  utput of EXPLAIN
19670 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d   QUERY PLAN comm
19680 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a  ands does not .*
19690 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74  * include output
196a0 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69   for any operati
196b0 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ons performed by
196c0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
196d0 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f  s. This.** optio
196e0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  n is used to set
196f0 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64   or clear (the d
19700 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74  efault) a flag t
19710 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73  hat governs this
19720 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68  .** behavior. Th
19730 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19740 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
19750 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
19760 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f   integer -.** no
19770 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65  n-zero to enable
19780 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67   output for trig
19790 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72  ger programs, or
197a0 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65   zero to disable
197b0 20 69 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f   it..** The seco
197c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
197d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
197e0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
197f0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
19800 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
19810 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
19820 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
19830 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
19840 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
19850 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
19860 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
19870 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ** </dd>.** </dl
19880 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
19890 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
198a0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
198b0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
198c0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
198d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
198e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
198f0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
19900 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
19910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19920 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19930 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
19940 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
19950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19960 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19970 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19980 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
19990 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
199a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
199b0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
199c0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
199d0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
199e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
199f0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
19a00 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
19a10 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19a20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19a30 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
19a40 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
19a50 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19a60 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19a70 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
19a80 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
19a90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19ab0 4e 46 49 47 5f 46 55 4c 4c 5f 45 51 50 20 20 20  NFIG_FULL_EQP   
19ac0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
19ad0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
19ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19af0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
19b00 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
19b10 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
19b20 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19b30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
19b40 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19b50 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
19b60 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
19b70 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
19b80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
19b90 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
19ba0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
19bb0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
19bc0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
19bd0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
19be0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
19bf0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
19c00 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
19c10 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
19c20 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
19c30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c40 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
19c50 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
19c60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19c70 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
19c80 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
19c90 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
19ca0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19cb0 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
19cc0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
19cd0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
19ce0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
19cf0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
19d00 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
19d10 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
19d20 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
19d30 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
19d40 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
19d50 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
19d60 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
19d70 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
19d80 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
19d90 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
19da0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
19db0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
19dc0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
19dd0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
19de0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
19df0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
19e00 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
19e10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
19e20 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19e30 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
19e40 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74  face usually ret
19e50 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
19e60 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20   of.** the most 
19e70 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
19e80 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
19e90 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
19ea0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
19eb0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
19ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49  connection D. ^I
19ed0 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
19ee0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19ef0 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  es are not.** re
19f00 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73  corded. ^If no s
19f10 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19f20 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
19f30 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20  ables have ever 
19f40 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20  occurred .** on 
19f50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19f60 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20  nection D, then 
19f70 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19f80 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
19f90 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a  urns .** zero..*
19fa0 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20  *.** As well as 
19fb0 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61  being set automa
19fc0 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20  tically as rows 
19fd0 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74  are inserted int
19fe0 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  o database.** ta
19ff0 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  bles, the value 
1a000 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
1a010 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1a020 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20   set explicitly 
1a030 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
1a040 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1a050 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f  owid()].**.** So
1a060 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  me virtual table
1a070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1a080 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73   may INSERT rows
1a090 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
1a0a0 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  es as.** part of
1a0b0 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72   committing a tr
1a0c0 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20  ansaction (e.g. 
1a0d0 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63  to flush data ac
1a0e0 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d  cumulated in mem
1a0f0 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e  ory.** to disk).
1a100 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75   In this case su
1a110 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1a120 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1a130 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64  return the rowid
1a140 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a150 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e  ith these intern
1a160 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74  al INSERT operat
1a170 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64  ions, which lead
1a180 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69  s to .** unintui
1a190 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69  tive results. Vi
1a1a0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1a1b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74  ementations that
1a1c0 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77   do write to row
1a1d0 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20  id.** tables in 
1a1e0 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f  this way can avo
1a1f0 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20  id this problem 
1a200 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65  by restoring the
1a210 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f   original .** ro
1a220 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20  wid value using 
1a230 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1a240 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a250 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  ] before returni
1a260 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74  ng .** control t
1a270 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a  o the user..**.*
1a280 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
1a290 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
1a2a0 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20   a trigger then 
1a2b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
1a2c0 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  l .** return the
1a2d0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
1a2e0 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20  inserted row as 
1a2f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1a300 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69  ger is .** runni
1a310 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69  ng. Once the tri
1a320 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64  gger program end
1a330 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1a340 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
1a350 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
1a360 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
1a370 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
1a380 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e  ger was fired.)^
1a390 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
1a3a0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
1a3b0 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
1a3c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
1a3d0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
1a3e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
1a3f0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
1a400 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a410 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
1a420 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
1a430 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
1a440 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
1a450 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
1a460 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
1a470 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
1a480 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
1a490 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a4a0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
1a4b0 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
1a4c0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
1a4d0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
1a4e0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
1a4f0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
1a500 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
1a510 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
1a520 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
1a530 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
1a540 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
1a550 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
1a560 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
1a570 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
1a580 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
1a590 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
1a5a0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
1a5b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1a5c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
1a5d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
1a5e0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1a5f0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
1a600 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
1a610 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
1a620 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
1a630 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
1a640 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
1a650 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
1a660 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
1a670 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
1a680 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
1a690 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
1a6a0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
1a6b0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a6c0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a6d0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
1a6e0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
1a6f0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
1a700 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1a710 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
1a720 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a730 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
1a740 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
1a750 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
1a760 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1a770 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
1a780 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a790 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
1a7a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1a7b0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
1a7c0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
1a7d0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
1a7e0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
1a7f0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
1a800 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
1a810 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1a820 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1a830 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
1a840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a850 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e   Set the Last In
1a860 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65  sert Rowid value
1a870 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  ..** METHOD: sql
1a880 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
1a890 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1a8a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20  insert_rowid(D, 
1a8b0 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73  R) method allows
1a8c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a8d0 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76   to.** set the v
1a8e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a8f0 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
1a900 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a910 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77  id(D) to R .** w
1a920 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67  ithout inserting
1a930 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20   a row into the 
1a940 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69  database..*/.voi
1a950 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  d sqlite3_set_la
1a960 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a970 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33  sqlite3*,sqlite3
1a980 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
1a990 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
1a9a0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
1a9b0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1a9c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a9d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a9e0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1a9f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1aa00 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
1aa10 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1aa20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1aa30 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
1aa40 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1aa50 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
1aa60 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61  ment on the data
1aa70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1aa80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1aa90 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e   only parameter.
1aaa0 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61  .** ^Executing a
1aab0 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1aac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
1aad0 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  oes not modify t
1aae0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1aaf0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1ab00 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ction..**.** ^On
1ab10 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1ab20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  directly by the 
1ab30 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1ab40 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1ab50 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  nt are.** consid
1ab60 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79  ered - auxiliary
1ab70 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
1ab80 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  by [CREATE TRIGG
1ab90 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20  ER | triggers], 
1aba0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1abb0 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45   actions] or [RE
1abc0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
1abd0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1abe0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1abf0 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20   .** Changes to 
1ac00 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1ac10 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a  intercepted by .
1ac20 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  ** [INSTEAD OF t
1ac30 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44  rigger | INSTEAD
1ac40 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72   OF triggers] ar
1ac50 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e  e not counted. ^
1ac60 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65  The value .** re
1ac70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1ac80 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65  3_changes() imme
1ac90 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e  diately after an
1aca0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1acb0 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74  or .** DELETE st
1acc0 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61  atement run on a
1acd0 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20   view is always 
1ace0 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67  zero. Only chang
1acf0 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20  es made to real 
1ad00 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63  .** tables are c
1ad10 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
1ad20 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f  ings are more co
1ad30 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65  mplicated if the
1ad40 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1ad50 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  () function is.*
1ad60 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65  * executed while
1ad70 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1ad80 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54  am is running. T
1ad90 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69  his may happen i
1ada0 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  f the.** program
1adb0 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67   uses the [chang
1adc0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1add0 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f  n], or if some o
1ade0 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ther callback.**
1adf0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65   function invoke
1ae00 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  s sqlite3_change
1ae10 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73  s() directly. Es
1ae20 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a  sentially:.** .*
1ae30 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
1ae40 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69   ^(Before enteri
1ae50 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  ng a trigger pro
1ae60 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72  gram the value r
1ae70 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1ae80 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61       sqlite3_cha
1ae90 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1aea0 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20  is saved. After 
1aeb0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1aec0 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68  ram .**        h
1aed0 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65  as finished, the
1aee0 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20   original value 
1aef0 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a  is restored.)^.*
1af00 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57  * .**   <li> ^(W
1af10 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1af20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53  program each INS
1af30 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20  ERT, UPDATE and 
1af40 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20  DELETE .**      
1af50 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73    statement sets
1af60 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1af70 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1af80 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1af90 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74      upon complet
1afa0 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f  ion as normal. O
1afb0 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76  f course, this v
1afc0 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e  alue will not in
1afd0 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20  clude .**       
1afe0 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72   any changes per
1aff0 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72  formed by sub-tr
1b000 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73  iggers, as the s
1b010 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b020 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75   .**        valu
1b030 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20  e will be saved 
1b040 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74  and restored aft
1b050 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67  er each sub-trig
1b060 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a  ger has run.)^.*
1b070 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e  * </ul>.** .** ^
1b080 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
1b090 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29  if the changes()
1b0a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f   SQL function (o
1b0b0 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73  r similar) is us
1b0c0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
1b0d0 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  st INSERT, UPDAT
1b0e0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1b0f0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1b100 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72  rigger, it .** r
1b110 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
1b120 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   as set when the
1b130 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65   calling stateme
1b140 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69  nt began executi
1b150 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ng..** ^If it is
1b160 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63   used by the sec
1b170 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ond or subsequen
1b180 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74  t such statement
1b190 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1b1a0 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74  r .** program, t
1b1b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b1c0 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e  d reflects the n
1b1d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
1b1e0 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  dified by the .*
1b1f0 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52  * previous INSER
1b200 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1b210 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1b220 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
1b230 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  igger..**.** See
1b240 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1b250 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b260 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1b270 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1b280 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1b290 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
1b2a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1b2b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1b2c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1b2d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1b2e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1b2f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1b300 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1b310 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1b320 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1b330 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
1b340 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1b350 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1b360 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b370 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1b380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b390 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1b3a0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1b3b0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1b3c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1b3d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b3e0 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1b3f0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1b400 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1b410 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1b420 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1b430 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1b440 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1b450 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1b460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b470 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1b480 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1b490 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1b4a0 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1b4b0 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1b4c0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1b4d0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1b4e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1b4f0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1b500 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1b510 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1b520 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1b530 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1b540 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1b550 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1b560 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1b570 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1b580 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1b590 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1b5a0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1b5b0 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1b5c0 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1b5d0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1b5e0 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1b5f0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1b600 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1b610 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1b620 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1b630 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1b640 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1b650 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1b660 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1b670 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1b680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1b690 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1b6a0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1b6b0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1b6c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1b6d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1b6e0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1b6f0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1b700 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1b710 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1b720 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1b730 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1b740 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
1b750 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1b760 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1b770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b780 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
1b790 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
1b7a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b7b0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1b7c0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
1b7d0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
1b7e0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
1b7f0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
1b800 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
1b810 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
1b820 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
1b830 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
1b840 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
1b850 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
1b860 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
1b870 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
1b880 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
1b890 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
1b8a0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
1b8b0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
1b8c0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
1b8d0 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
1b8e0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1b8f0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
1b900 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
1b910 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
1b920 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
1b930 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
1b940 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
1b950 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
1b960 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
1b970 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1b980 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1b990 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
1b9a0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
1b9b0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
1b9c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b9d0 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
1b9e0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
1b9f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
1ba00 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
1ba10 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
1ba20 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
1ba30 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
1ba40 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
1ba50 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
1ba60 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
1ba70 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
1ba80 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
1ba90 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
1baa0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
1bab0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
1bac0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
1bad0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1bae0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
1baf0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
1bb00 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
1bb10 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
1bb20 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
1bb30 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
1bb40 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
1bb50 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1bb60 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
1bb70 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
1bb80 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
1bb90 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
1bba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bbb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1bbc0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
1bbd0 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
1bbe0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
1bbf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bc00 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
1bc10 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
1bc20 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
1bc30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1bc40 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1bc50 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1bc60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1bc70 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
1bc80 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
1bc90 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
1bca0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
1bcb0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
1bcc0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
1bcd0 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
1bce0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1bcf0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
1bd00 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
1bd10 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1bd20 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1bd30 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1bd40 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
1bd50 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
1bd60 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
1bd70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1bd80 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
1bd90 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
1bda0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
1bdb0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
1bdc0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
1bdd0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1bde0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
1bdf0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
1be00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1be10 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1be20 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1be30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1be40 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
1be50 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1be60 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
1be70 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1be80 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
1be90 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
1bea0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
1beb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1bec0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
1bed0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
1bee0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
1bef0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
1bf00 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
1bf10 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
1bf20 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
1bf30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
1bf40 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
1bf50 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
1bf60 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
1bf70 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
1bf80 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
1bf90 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
1bfa0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
1bfb0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
1bfc0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
1bfd0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
1bfe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
1bff0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
1c000 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
1c010 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
1c020 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
1c030 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
1c040 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
1c050 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
1c060 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
1c070 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
1c080 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
1c090 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
1c0a0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
1c0b0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
1c0c0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
1c0d0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
1c0e0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
1c0f0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
1c100 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
1c110 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
1c120 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
1c130 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
1c140 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1c150 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
1c160 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
1c170 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
1c180 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
1c190 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
1c1a0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1c1c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
1c1d0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
1c1e0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
1c1f0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
1c200 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1c210 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
1c220 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
1c230 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1c240 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
1c250 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
1c260 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
1c270 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
1c280 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
1c290 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
1c2a0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
1c2b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
1c2c0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
1c2d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c2e0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
1c2f0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
1c300 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c310 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
1c320 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
1c330 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
1c340 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
1c350 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
1c360 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
1c370 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
1c380 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
1c390 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1c3a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c3b0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
1c3c0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
1c3d0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1c3e0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
1c3f0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
1c400 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1c410 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1c420 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
1c430 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1c440 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
1c450 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
1c460 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1c470 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
1c480 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1c490 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1c4a0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
1c4b0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
1c4c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1c4d0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1c4e0 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
1c4f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
1c500 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
1c510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c520 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
1c530 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
1c540 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
1c550 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1c560 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
1c570 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
1c580 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
1c590 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c5a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
1c5b0 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
1c5c0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c5d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c5e0 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
1c5f0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1c600 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
1c610 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1c620 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
1c630 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
1c640 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
1c650 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
1c660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c670 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
1c680 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
1c690 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
1c6a0 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
1c6b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c6c0 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
1c6d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
1c6e0 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
1c6f0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c700 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
1c710 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
1c720 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1c730 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1c740 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1c750 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
1c760 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1c770 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1c780 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1c790 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c7a0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1c7b0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1c7c0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1c7d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1c7e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1c7f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1c800 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1c810 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1c820 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1c830 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1c840 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1c850 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c860 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c870 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1c880 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1c890 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1c8a0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1c8b0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1c8c0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1c8d0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1c8e0 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
1c8f0 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
1c900 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1c910 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1c920 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c930 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1c940 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1c950 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1c960 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1c970 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1c980 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
1c990 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
1c9a0 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
1c9b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c9c0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1c9d0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
1c9e0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
1c9f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1ca00 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
1ca10 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1ca20 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1ca30 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1ca40 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1ca50 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1ca60 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1ca70 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1ca80 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1ca90 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1caa0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1cab0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1cac0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1cad0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1cae0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1caf0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1cb00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1cb10 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1cb20 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1cb30 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1cb40 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1cb50 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1cb60 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1cb70 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1cb80 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1cb90 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1cba0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1cbb0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1cbc0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1cbd0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1cbe0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1cbf0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1cc00 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1cc10 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1cc20 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1cc30 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1cc40 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1cc50 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1cc60 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1cc70 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1cc80 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1cc90 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1cca0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1ccb0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1ccc0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1ccd0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1cce0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1ccf0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1cd00 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1cd10 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1cd20 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1cd30 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1cd40 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1cd50 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1cd60 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1cd70 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1cd80 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1cd90 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1cda0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1cdb0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1cdc0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1cdd0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1cde0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1cdf0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1ce00 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1ce10 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1ce20 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1ce30 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1ce40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1ce50 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1ce60 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1ce70 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1ce80 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1ce90 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1cea0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1ceb0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1cec0 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1ced0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cee0 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1cef0 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1cf00 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1cf10 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1cf20 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1cf30 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1cf40 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1cf50 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1cf60 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1cf70 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1cf80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf90 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1cfa0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cfb0 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1cfc0 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1cfd0 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1cfe0 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1cff0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1d000 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1d010 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1d020 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1d030 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1d040 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1d050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1d060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d070 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1d080 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1d090 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1d0a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1d0b0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28  sqlite3*,int(*)(
1d0c0 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a  void*,int),void*
1d0d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d0e0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1d0f0 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44  imeout.** METHOD
1d100 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1d110 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1d120 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
1d130 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
1d140 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
1d150 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
1d160 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
1d170 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
1d180 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
1d190 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
1d1a0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
1d1b0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
1d1c0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
1d1d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1d1e0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
1d1f0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
1d200 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
1d210 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1d220 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
1d230 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
1d240 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
1d250 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
1d260 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
1d270 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
1d280 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1d290 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1d2a0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1d2b0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1d2c0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1d2d0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1d2e0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1d2f0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d300 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d310 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1d320 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d340 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20  n] at any given 
1d350 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1d360 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1d370 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1d380 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1d390 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1d3a0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1d3b0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1d3c0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1d3d0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1d3e0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
1d3f0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
1d400 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1d410 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d420 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1d430 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1d440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d450 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1d460 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1d470 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54  g Queries.** MET
1d480 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1d490 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1d4a0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1d4b0 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1d4c0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1d4d0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1d4e0 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1d4f0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1d500 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1d510 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1d520 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1d530 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1d540 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1d550 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1d560 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d570 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1d580 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1d590 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1d5a0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1d5b0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1d5c0 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1d5d0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1d5e0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1d5f0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d600 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1d610 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1d620 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1d630 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1d640 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1d650 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1d660 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1d670 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1d680 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1d690 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1d6a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1d6b0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1d6c0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1d6d0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1d6e0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1d6f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1d700 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1d710 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1d720 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1d730 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1d740 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1d750 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1d760 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1d770 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1d780 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1d790 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1d7a0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1d7b0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1d7c0 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1d7d0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1d7e0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1d7f0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1d800 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1d810 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1d820 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1d830 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1d840 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1d850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1d860 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1d870 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1d880 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1d890 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1d8a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1d8b0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1d8c0 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1d8d0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1d8e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1d8f0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1d900 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1d910 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1d920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1d930 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1d940 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1d950 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1d960 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1d970 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1d980 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1d990 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d9a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d9b0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1d9c0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1d9d0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1d9e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1d9f0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1da00 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1da10 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1da20 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1da30 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1da40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1da50 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1da60 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1da70 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1da80 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1da90 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1daa0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1dab0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1dac0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1dad0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1dae0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1daf0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1db00 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1db10 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1db20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1db30 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1db40 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1db50 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1db60 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1db70 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1db80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1db90 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1dba0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1dbb0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1dbc0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1dbd0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1dbe0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1dbf0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1dc00 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1dc10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1dc20 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1dc30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dc40 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1dc50 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1dc60 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1dc70 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1dc80 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1dc90 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1dca0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1dcb0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1dcc0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1dcd0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1dce0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1dcf0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1dd00 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1dd10 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1dd20 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1dd30 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1dd40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1dd50 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1dd60 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1dd70 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1dd80 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1dd90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1dda0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1ddb0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1ddc0 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1ddd0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1dde0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1ddf0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1de00 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1de10 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1de20 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1de30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1de40 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1de50 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1de60 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1de70 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1de80 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1de90 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1dea0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1deb0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1dec0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ded0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1dee0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1def0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1df00 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1df10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1df20 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1df30 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1df40 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1df50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1df60 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1df70 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1df80 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1df90 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1dfa0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1dfb0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1dfc0 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1dfd0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1dfe0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1dff0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1e000 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1e010 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1e020 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1e030 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1e040 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1e050 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1e060 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1e070 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1e080 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1e090 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1e0a0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1e0b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1e0c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1e0d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1e0e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1e0f0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1e100 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1e110 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1e120 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1e130 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1e140 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1e150 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1e160 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1e170 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1e180 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1e190 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1e1a0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1e1b0 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1e1c0 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1e1d0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1e1e0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1e1f0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1e200 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1e210 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1e220 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
1e230 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1e240 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1e250 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1e260 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1e270 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1e280 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1e290 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e2a0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1e2b0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1e2c0 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1e2d0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1e2e0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1e2f0 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1e300 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1e310 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1e320 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1e330 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1e340 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1e350 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1e360 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1e370 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1e380 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1e390 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1e3a0 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1e3b0 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1e3c0 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1e3d0 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1e3e0 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1e3f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1e400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e410 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1e420 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e430 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1e440 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1e450 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1e460 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e470 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1e480 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e490 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e4a0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e4b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e4c0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e4d0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e4e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e4f0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e500 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e510 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1e520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1e530 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1e540 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1e550 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1e560 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1e570 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1e580 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1e590 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1e5a0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1e5b0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1e5c0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1e5d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1e5e0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1e5f0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e600 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1e610 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1e620 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1e630 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1e640 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1e650 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1e660 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1e670 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1e680 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1e690 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1e6a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1e6b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1e6c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1e6d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1e6e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1e6f0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1e700 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1e710 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1e720 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1e730 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1e740 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1e750 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1e760 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1e770 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1e780 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1e790 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1e7a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1e7b0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1e7c0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1e7d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1e7e0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1e7f0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1e800 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1e810 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1e820 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1e830 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1e840 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1e850 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1e860 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1e870 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1e880 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1e890 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1e8a0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1e8b0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1e8c0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1e8d0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1e8e0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1e8f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1e900 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1e910 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1e920 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e930 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1e940 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1e950 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1e960 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1e970 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1e980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e990 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1e9a0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1e9b0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1e9c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e9d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1e9e0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1e9f0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1ea00 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1ea10 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ea20 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1ea30 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ea40 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1ea50 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1ea60 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1ea70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1ea80 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ea90 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1eaa0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1eab0 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1eac0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1ead0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1eae0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1eaf0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1eb00 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1eb10 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1eb20 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1eb30 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1eb40 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1eb50 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1eb60 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1eb70 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1eb80 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1eb90 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1eba0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1ebb0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1ebc0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1ebd0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1ebe0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1ebf0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1ec00 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1ec10 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1ec20 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1ec30 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1ec40 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1ec50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ec60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ec70 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1ec80 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1ec90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1eca0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1ecb0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1ecc0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1ecd0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1ece0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ecf0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1ed00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1ed10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1ed20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1ed30 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1ed40 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1ed50 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1ed60 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1ed70 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1ed80 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ed90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1eda0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1edb0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1edc0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1edd0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1ede0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1edf0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1ee00 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1ee10 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ee20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ee30 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1ee40 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1ee50 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1ee60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ee70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ee80 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1ee90 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1eea0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1eeb0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1eec0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1eed0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1eee0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1eef0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1ef00 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1ef10 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1ef20 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1ef30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ef40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1ef50 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1ef60 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1ef70 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1ef80 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1ef90 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1efa0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1efb0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1efc0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1efd0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1efe0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1eff0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1f000 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1f010 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1f020 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1f030 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1f040 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1f050 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1f060 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1f070 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1f080 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1f090 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1f0a0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1f0b0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1f0c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1f0d0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1f0e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1f0f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1f100 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f110 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1f120 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f130 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1f140 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1f150 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1f160 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1f170 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1f180 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1f190 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1f1a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f1b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1f1c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1f1d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1f1e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1f1f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1f200 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1f210 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1f220 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f230 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1f240 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1f250 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1f260 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1f270 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1f280 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1f290 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1f2a0 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1f2b0 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1f2c0 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1f2d0 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1f2e0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1f2f0 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1f300 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1f310 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1f320 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1f330 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1f340 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1f350 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1f360 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1f370 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1f380 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1f390 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1f3a0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1f3b0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1f3c0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1f3d0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1f3e0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1f3f0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1f400 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1f410 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1f420 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1f430 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1f440 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1f450 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f460 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1f470 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f480 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1f490 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f4a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1f4b0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1f4c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1f4d0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1f4e0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1f4f0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f500 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1f510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1f520 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1f530 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1f540 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1f550 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1f560 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1f570 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1f580 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1f590 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1f5a0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1f5b0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1f5c0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1f5d0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1f5e0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1f5f0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1f600 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1f610 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1f620 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1f630 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1f640 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1f650 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f660 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1f670 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f680 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1f690 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1f6a0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1f6b0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1f6c0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1f6d0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1f6e0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1f6f0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1f700 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1f710 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1f720 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1f730 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1f740 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1f750 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1f760 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1f770 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1f780 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1f790 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1f7a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
1f7b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f7c0 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
1f7d0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
1f7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1f7f0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1f800 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
1f810 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
1f820 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
1f830 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
1f840 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1f850 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1f860 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1f870 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1f880 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1f890 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1f8a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1f8b0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1f8c0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1f8d0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1f8e0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1f8f0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1f900 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1f910 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1f920 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f930 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1f940 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1f950 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1f960 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1f970 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1f980 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1f990 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1f9a0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1f9b0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1f9c0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1f9d0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1f9e0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1f9f0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1fa00 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1fa10 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1fa20 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1fa30 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1fa40 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1fa50 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1fa60 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1fa70 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1fa80 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1fa90 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1faa0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1fab0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1fac0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1fad0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1fae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1faf0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
1fb00 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1fb10 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1fb20 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1fb30 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
1fb40 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
1fb50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
1fb60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fb70 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
1fb80 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1fb90 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1fba0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1fbb0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1fbc0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fbd0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
1fbe0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
1fbf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fc00 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
1fc10 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1fc20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1fc30 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1fc40 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1fc50 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
1fc60 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1fc70 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1fc80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1fc90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1fca0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1fcb0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1fcc0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
1fcd0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1fce0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
1fcf0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1fd00 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1fd10 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1fd20 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1fd30 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1fd40 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1fd50 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1fd60 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1fd70 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1fd80 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1fd90 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
1fda0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1fdb0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1fdc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fdd0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
1fde0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
1fdf0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
1fe00 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
1fe10 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
1fe20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fe30 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
1fe40 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
1fe50 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
1fe60 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
1fe70 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
1fe80 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
1fe90 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1fea0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1feb0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
1fec0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1fed0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
1fee0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
1fef0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
1ff00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1ff10 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1ff20 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
1ff30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ff40 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
1ff50 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
1ff60 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1ff70 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
1ff80 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
1ff90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
1ffa0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
1ffb0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1ffc0 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
1ffd0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
1ffe0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
1fff0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
20000 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
20010 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
20020 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
20030 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
20040 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20050 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
20060 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
20070 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
20080 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
20090 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
200a0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
200b0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
200c0 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
200d0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
200e0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
200f0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
20100 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
20110 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
20120 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
20130 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
20140 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
20150 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
20160 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
20170 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
20180 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
20190 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
201a0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
201b0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
201c0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
201d0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
201e0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
201f0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
20200 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
20210 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
20220 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
20230 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
20240 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
20250 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
20260 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
20270 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
20280 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
20290 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
202a0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
202b0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
202c0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
202d0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
202e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
202f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
20300 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
20310 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
20320 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
20330 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
20340 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
20350 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
20360 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
20370 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
20380 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
20390 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
203a0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
203b0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
203c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
203d0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
203e0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
203f0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
20400 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
20410 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
20420 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
20430 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
20440 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
20450 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
20460 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
20470 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
20480 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
20490 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
204a0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
204b0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
204c0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
204d0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
204e0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
204f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
20500 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
20510 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
20520 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
20530 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
20540 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
20550 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
20560 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
20570 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
20580 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
20590 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
205a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
205b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
205c0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
205d0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
205e0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
205f0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
20600 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
20610 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
20620 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
20630 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
20640 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
20650 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
20660 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
20670 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20680 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
20690 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
206a0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
206b0 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
206c0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
206d0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
206e0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
206f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
20700 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
20710 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
20720 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
20730 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
20740 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
20750 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
20760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
20770 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
20780 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
20790 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
207a0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
207b0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
207c0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
207d0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
207e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
207f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20800 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
20810 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
20820 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
20830 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
20840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20850 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
20860 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
20870 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
20880 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
208a0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
208b0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
208c0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
208d0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
208e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
208f0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20900 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
20910 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
20920 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
20930 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20940 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
20950 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20960 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
20970 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
20980 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
20990 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
209a0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
209b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
209c0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
209d0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
209e0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
209f0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
20a00 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
20a10 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
20a20 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
20a30 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
20a40 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
20a50 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
20a60 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
20a70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
20a80 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
20a90 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
20aa0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
20ab0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
20ac0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
20ad0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20ae0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
20af0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
20b00 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
20b10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20b20 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
20b30 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
20b40 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
20b50 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20b60 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
20b70 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20b80 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
20b90 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
20ba0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
20bb0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
20bc0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
20bd0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
20be0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
20bf0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
20c00 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
20c10 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
20c20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
20c30 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
20c40 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
20c50 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
20c60 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
20c70 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
20c80 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
20c90 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
20ca0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
20cb0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
20cc0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
20cd0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
20ce0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
20cf0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
20d00 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
20d10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
20d20 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
20d30 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
20d40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
20d50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
20d60 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
20d70 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
20d80 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
20d90 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
20da0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
20db0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
20dc0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
20dd0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
20de0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
20df0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
20e00 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
20e10 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
20e20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
20e30 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
20e40 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
20e50 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
20e60 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
20e70 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
20e80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
20e90 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
20ea0 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
20eb0 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
20ec0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
20ed0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
20ee0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
20ef0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
20f00 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
20f10 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
20f20 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
20f30 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
20f40 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
20f50 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
20f60 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
20f70 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
20f80 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
20f90 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
20fa0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
20fb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
20fc0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
20fd0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
20fe0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
20ff0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
21000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21010 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
21020 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
21030 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
21040 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b  OD: sqlite3.** K
21050 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72  EYWORDS: {author
21060 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a  izer callback}.*
21070 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
21080 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
21090 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
210a0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
210b0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
210c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
210d0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
210e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
210f0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
21100 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21110 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
21120 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
21130 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
21140 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
21150 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
21160 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
21170 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
21180 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21190 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
211a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
211b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
211c0 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64  16_v2()],.** and
211d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
211e0 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20  e16_v3()].  ^At 
211f0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
21200 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
21210 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
21220 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
21230 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
21240 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
21250 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
21260 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21270 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
21280 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
21290 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
212a0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
212b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
212c0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
212d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
212e0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
212f0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
21300 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
21310 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
21320 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
21330 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21340 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
21350 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
21360 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
21370 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
21380 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
21390 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
213a0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
213b0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
213c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
213d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
213e0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
213f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
21400 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
21410 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
21420 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
21430 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21440 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
21450 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
21460 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
21470 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
21480 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
21490 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
214a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
214b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
214c0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
214d0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
214e0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
214f0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
21500 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
21510 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
21520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21530 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
21540 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
21550 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
21560 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
21570 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
21580 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
21590 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
215a0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
215b0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
215c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
215d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
215e0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
215f0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
21600 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
21610 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
21620 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
21630 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
21640 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
21650 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
21660 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21670 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
21680 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
21690 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
216a0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
216b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
216c0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
216d0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
216e0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
216f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
21700 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f  e either NULL po
21710 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74  inters or zero-t
21720 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
21730 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69  s.** that contai
21740 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  n additional det
21750 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
21760 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21770 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69  orized..** Appli
21780 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77  cations must alw
21790 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20  ays be prepared 
217a0 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e  to encounter a N
217b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61  ULL pointer in a
217c0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69  ny.** of the thi
217d0 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  rd through the s
217e0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
217f0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  of the authoriza
21800 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
21810 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
21820 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
21830 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
21840 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21850 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
21860 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
21870 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
21880 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
21890 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
218a0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
218b0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
218c0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
218d0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
218e0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
218f0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
21900 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
21910 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
21920 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
21930 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
21940 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
21950 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
21960 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
21970 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
21980 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57  f a table..** ^W
21990 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72  hen a table is r
219a0 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b  eferenced by a [
219b0 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63  SELECT] but no c
219c0 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65  olumn values are
219d0 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72  .** extracted fr
219e0 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66  om that table (f
219f0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20  or example in a 
21a00 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53  query like.** "S
21a10 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46  ELECT count(*) F
21a20 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74  ROM tab") then t
21a30 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  he [SQLITE_READ]
21a40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21a50 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  back.** is invok
21a60 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74  ed once for that
21a70 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f   table with a co
21a80 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69  lumn name that i
21a90 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
21aa0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  g..** ^If the ac
21ab0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21ac0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
21ad0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21ae0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
21af0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
21b00 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
21b10 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
21b20 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
21b30 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
21b40 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
21b50 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
21b60 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
21b70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
21b80 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
21b90 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
21ba0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
21bb0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
21bc0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
21bd0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
21be0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
21bf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
21c00 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
21c10 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
21c20 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
21c30 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
21c40 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
21c50 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
21c60 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
21c70 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
21c80 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
21c90 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
21ca0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
21cb0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
21cc0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
21cd0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
21ce0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
21cf0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
21d00 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
21d10 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
21d20 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
21d30 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
21d40 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
21d50 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
21d60 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
21d70 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
21d80 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
21d90 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
21da0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
21db0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
21dc0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
21dd0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
21de0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
21df0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
21e00 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
21e10 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
21e20 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
21e30 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
21e40 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
21e50 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
21e60 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
21e70 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
21e80 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
21e90 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
21ea0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
21eb0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
21ec0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
21ed0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
21ee0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
21ef0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
21f00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
21f10 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
21f20 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
21f30 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
21f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
21f50 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
21f60 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
21f70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21f80 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
21f90 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
21fa0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
21fb0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
21fc0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
21fd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
21fe0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
21ff0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
22000 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
22010 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22020 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
22030 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
22040 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
22050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22060 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
22070 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22080 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
22090 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
220a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
220b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
220c0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
220d0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
220e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
220f0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
22100 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
22110 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
22120 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
22130 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
22140 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
22150 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
22160 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
22170 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
22180 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
22190 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
221a0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
221b0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
221c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
221d0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
221e0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
221f0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
22200 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
22210 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
22220 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
22230 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
22240 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
22250 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22260 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
22270 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
22280 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
22290 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
222a0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
222b0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
222c0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
222d0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
222e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
222f0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
22300 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
22310 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
22320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
22330 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
22340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
22350 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
22360 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
22370 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
22380 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
22390 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
223a0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
223b0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
223c0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
223d0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
223e0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
223f0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
22400 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
22410 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
22420 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
22430 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
22440 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22450 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
22460 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
22470 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
22480 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
22490 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
224a0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
224b0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
224c0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
224d0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
224e0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
224f0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
22500 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
22510 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
22520 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
22530 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
22540 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
22550 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
22560 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
22570 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
22580 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
22590 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
225a0 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
225b0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
225c0 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
225d0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
225e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
225f0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
22600 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
22610 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
22620 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
22630 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
22640 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
22650 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
22660 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
22670 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
22680 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
22690 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
226a0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
226b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
226c0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
226d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
226e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
226f0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
22700 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
22710 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
22720 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
22730 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
22740 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
22750 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
22760 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
22770 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
22780 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
22790 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
227a0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
227b0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
227c0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
227d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
227e0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
227f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
22800 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
22810 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
22820 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
22830 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
22840 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
22850 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
22860 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
22870 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
22880 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
22890 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
228a0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
228b0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
228c0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
228d0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
228e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
228f0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
22900 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
22910 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22920 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22930 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
22940 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
22950 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
22960 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
22970 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
22980 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22990 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
229a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
229b0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
229c0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
229d0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
229e0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
229f0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
22a00 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
22a10 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
22a20 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
22a30 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
22a40 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
22a50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22a60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
22a70 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
22a80 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
22a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22aa0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
22ab0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
22ac0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22ad0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22af0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
22b00 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
22b10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22b20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22b30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22b40 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
22b50 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
22b60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22b70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22b80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22b90 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
22ba0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
22bb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22bc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22bd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22be0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
22bf0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
22c00 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22c10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22c20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22c30 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
22c40 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22c50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22c60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22c70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22c80 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
22c90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22ca0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22cb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22cc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
22cd0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
22ce0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22cf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22d00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22d10 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
22d20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
22d30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22d40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22d50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22d60 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
22d70 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
22d80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22d90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22da0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22db0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
22dc0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
22dd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22de0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22df0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22e00 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
22e10 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
22e20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22e30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22e40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22e50 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
22e60 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
22e70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22e80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22e90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ea0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
22eb0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
22ec0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22ed0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ef0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
22f00 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
22f10 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22f20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22f40 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
22f50 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
22f60 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22f70 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22f80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22f90 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
22fa0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
22fb0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22fc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
22fe0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
22ff0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
23000 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23010 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23020 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
23030 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
23040 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
23050 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
23060 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
23070 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
23080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23090 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
230a0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
230b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
230c0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
230d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
230e0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
230f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23100 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23110 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
23120 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
23130 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
23140 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23150 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23160 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
23170 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
23180 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23190 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
231a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
231b0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
231c0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
231d0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
231e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
231f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23200 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
23210 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
23220 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
23230 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23240 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23250 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
23260 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
23270 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
23280 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23290 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
232a0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
232b0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
232c0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
232d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
232e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
232f0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
23300 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
23310 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23320 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23340 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
23350 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
23360 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
23370 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
23380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23390 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
233a0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
233b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
233c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
233d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
233e0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
233f0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
23400 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
23410 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
23420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
23430 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
23440 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
23450 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
23460 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
23470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
23480 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
23490 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
234a0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
234b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
234c0 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
234d0 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
234e0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
234f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
23500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
23510 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
23520 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
23530 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
23540 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
23550 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
23560 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
23570 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
23580 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
23590 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
235a0 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
235b0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
235c0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
235d0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
235e0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
235f0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
23600 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
23610 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
23620 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
23630 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
23640 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
23650 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
23660 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
23670 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
23680 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
23690 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
236a0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
236b0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
236c0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
236d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
236e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
236f0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
23700 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
23710 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
23720 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
23730 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
23740 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
23750 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
23760 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
23770 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
23780 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
23790 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
237a0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
237b0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
237c0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
237d0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
237e0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
237f0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
23800 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
23810 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
23820 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
23830 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
23840 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
23850 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
23860 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
23870 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
23880 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
23890 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
238a0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
238b0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
238c0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
238d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
238e0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
238f0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
23900 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
23910 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
23920 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
23930 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
23940 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
23950 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
23960 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
23970 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
23980 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
23990 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
239a0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
239b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
239c0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
239d0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
239e0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
239f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
23a00 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
23a10 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
23a20 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
23a30 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
23a40 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
23a50 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
23a60 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
23a70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23a80 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
23a90 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
23aa0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
23ab0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
23ac0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
23ad0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
23ae0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
23af0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
23b00 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
23b10 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
23b20 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
23b30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23b40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
23b50 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
23b60 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
23b70 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
23b80 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
23b90 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
23ba0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23bb0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
23bc0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
23bd0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
23be0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
23bf0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
23c00 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
23c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23c20 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
23c30 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
23c40 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
23c50 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
23c60 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
23c70 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
23c80 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
23c90 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
23ca0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
23cb0 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
23cc0 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
23cd0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
23ce0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
23cf0 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20  ace_v2()] is an 
23d00 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
23d10 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
23d20 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
23d30 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
23d40 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
23d50 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
23d60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
23d70 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
23d80 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23d90 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
23da0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
23db0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
23dc0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
23dd0 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23de0 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
23df0 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
23e00 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23e10 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23e20 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
23e30 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
23e40 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
23e50 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
23e60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
23e70 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
23e80 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
23e90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
23ea0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
23eb0 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
23ec0 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
23ed0 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
23ee0 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
23ef0 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
23f00 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
23f10 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
23f20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23f30 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
23f40 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
23f50 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
23f60 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
23f70 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
23f80 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
23f90 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
23fa0 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
23fb0 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
23fc0 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
23fd0 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
23fe0 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
23ff0 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
24000 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
24010 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
24020 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24030 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24040 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24050 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
24060 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
24070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24080 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
24090 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
240a0 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
240b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
240c0 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
240d0 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
240e0 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
240f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
24100 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
24110 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
24120 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
24130 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
24140 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
24150 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
24160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
24170 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
24180 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
24190 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
241a0 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
241b0 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
241c0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
241d0 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
241e0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
241f0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
24200 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
24210 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
24220 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
24230 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
24240 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
24250 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
24260 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
24270 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
24280 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
24290 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
242a0 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
242b0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
242c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
242d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
242e0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
242f0 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
24300 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
24310 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
24320 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
24330 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
24340 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
24350 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
24360 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
24370 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
24380 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24390 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
243a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
243b0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
243c0 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
243d0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
243e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
243f0 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
24400 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
24410 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
24420 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
24430 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
24440 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
24450 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
24460 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
24470 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
24480 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
24490 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
244a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
244b0 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
244c0 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
244d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
244e0 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
244f0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
24500 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
24510 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
24520 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
24530 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
24540 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
24550 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
24560 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
24570 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24580 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24590 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
245a0 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
245b0 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
245c0 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
245d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
245e0 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
245f0 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
24600 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24610 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
24620 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
24630 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
24640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
24650 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
24660 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
24670 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
24680 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
24690 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
246a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
246b0 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
246c0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
246d0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
246e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
246f0 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
24700 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
24710 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
24720 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
24730 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
24740 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
24750 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
24760 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
24770 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
24780 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
24790 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
247a0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
247b0 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
247c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
247d0 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
247e0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
247f0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
24800 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
24810 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
24820 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
24830 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
24840 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
24850 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
24860 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
24870 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
24880 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
24890 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
248a0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
248b0 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
248c0 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
248d0 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
248e0 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
248f0 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
24900 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
24910 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
24920 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
24930 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
24940 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
24950 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
24960 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
24970 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
24980 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
24990 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
249a0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
249b0 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
249c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
249d0 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
249e0 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
249f0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
24a00 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
24a10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
24a20 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
24a30 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
24a40 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
24a50 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
24a60 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
24a70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
24a80 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
24a90 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24aa0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
24ab0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
24ac0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
24ad0 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
24ae0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
24af0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
24b00 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
24b10 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
24b20 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
24b30 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
24b40 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
24b50 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
24b60 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
24b70 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
24b80 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
24b90 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
24ba0 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
24bb0 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
24bc0 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
24bd0 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
24be0 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
24bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
24c00 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
24c10 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
24c20 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
24c30 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
24c40 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
24c50 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
24c60 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
24c70 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
24c80 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
24c90 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
24ca0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
24cb0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
24cc0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
24cd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24ce0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
24cf0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
24d00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24d10 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
24d20 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
24d30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
24d40 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
24d50 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
24d60 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
24d70 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
24d80 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
24d90 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
24da0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
24db0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
24dc0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
24dd0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
24de0 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
24df0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
24e00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24e10 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
24e20 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
24e30 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
24e40 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
24e50 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
24e60 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
24e70 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
24e80 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
24e90 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
24ea0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
24eb0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
24ec0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
24ed0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
24ee0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
24ef0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24f00 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
24f10 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
24f20 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
24f30 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
24f40 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
24f50 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
24f60 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
24f70 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
24f80 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24f90 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
24fa0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
24fb0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
24fc0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
24fd0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
24fe0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
24ff0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
25000 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
25010 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
25020 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
25030 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
25040 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
25050 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
25060 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
25070 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
25080 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
25090 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
250a0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
250b0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
250c0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
250d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
250e0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
250f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25100 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
25110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25120 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
25130 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
25140 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
25150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25160 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
25170 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
25180 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
25190 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
251a0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
251b0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
251c0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
251d0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
251e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
251f0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
25200 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
25210 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
25220 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
25230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
25240 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
25250 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
25260 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
25270 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
25280 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
25290 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
252a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
252b0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
252c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
252d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
252e0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
252f0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
25300 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
25310 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
25320 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
25330 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
25340 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
25350 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
25360 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
25370 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
25380 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
25390 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
253a0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
253b0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
253c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
253d0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
253e0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
253f0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
25400 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
25410 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25420 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
25430 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
25440 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25450 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
25460 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
25470 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
25480 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
25490 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
254a0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
254b0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
254c0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
254d0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
254e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
254f0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
25500 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
25510 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
25520 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
25530 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
25540 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
25550 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
25560 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
25570 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
25580 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
25590 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
255a0 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
255b0 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
255c0 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
255d0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
255e0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
255f0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
25600 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
25610 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
25620 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
25630 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
25640 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
25650 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
25660 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
25670 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
25680 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
25690 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
256a0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
256b0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
256c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
256d0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
256e0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
256f0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
25700 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
25710 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
25720 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
25730 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
25740 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
25750 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
25760 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
25770 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
25780 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
25790 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
257a0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
257b0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
257c0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
257d0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
257e0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
257f0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
25800 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
25810 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
25820 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
25830 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
25840 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
25850 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
25860 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
25870 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
25880 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
25890 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
258a0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
258b0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
258c0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
258d0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
258e0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
258f0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25900 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
25910 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25920 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25930 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
25940 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
25950 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
25960 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
25970 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
25980 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
25990 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
259a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
259b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
259c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
259d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
259e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
259f0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
25a00 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
25a10 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
25a20 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
25a30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
25a40 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
25a50 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
25a60 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
25a70 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
25a80 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
25a90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
25aa0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
25ab0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25ac0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
25ad0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
25ae0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
25af0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25b00 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
25b10 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
25b20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
25b30 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
25b40 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
25b50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
25b60 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
25b70 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
25b80 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25b90 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
25ba0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
25bb0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
25bc0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25bd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25be0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
25bf0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
25c00 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
25c10 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
25c20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
25c30 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25c40 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
25c50 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
25c60 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
25c70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
25c80 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
25c90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25ca0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
25cb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25cc0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
25cd0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
25ce0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
25cf0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
25d00 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
25d10 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
25d20 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
25d30 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
25d40 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
25d50 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
25d60 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
25d70 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
25d80 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25d90 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
25da0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
25db0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25dc0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
25dd0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
25de0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
25df0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
25e00 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
25e10 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
25e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25e30 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
25e40 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
25e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
25e60 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
25e70 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
25e80 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
25e90 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25ea0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
25eb0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
25ec0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
25ed0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
25ee0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
25ef0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
25f00 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
25f10 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
25f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25f30 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
25f40 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
25f50 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
25f60 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
25f70 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
25f80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25fa0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
25fb0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
25fc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25fd0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
25fe0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25ff0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
26000 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
26010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26020 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
26030 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
26040 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
26050 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
26060 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
26070 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
26080 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
26090 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
260a0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
260b0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
260c0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
260d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
260e0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
260f0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
26100 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
26110 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
26120 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
26130 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26140 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
26150 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
26160 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
26170 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
26180 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
26190 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
261a0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
261b0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
261c0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
261d0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
261e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
261f0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
26200 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
26210 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
26220 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
26230 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
26240 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
26250 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
26260 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
26270 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
26280 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
26290 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
262a0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
262b0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
262c0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
262d0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
262e0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
262f0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
26300 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
26310 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
26320 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26330 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
26340 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
26350 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
26360 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
26370 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
26380 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
26390 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
263a0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
263b0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
263c0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
263d0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
263e0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
263f0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
26400 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
26410 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
26420 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
26430 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
26440 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
26450 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
26460 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
26470 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
26480 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26490 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
264a0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
264b0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
264c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
264d0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
264e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
264f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
26500 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
26510 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
26520 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
26530 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c  tion..** URI fil
26540 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
26550 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
26560 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
26570 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
26580 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
26590 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
265a0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
265b0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
265c0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
265d0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
265e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
265f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
26600 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
26610 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
26620 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
26630 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
26640 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
26650 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
26660 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
26670 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26680 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
26690 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
266a0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
266b0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
266c0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
266d0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
266e0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
266f0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
26700 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
26710 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
26720 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
26730 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
26740 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
26750 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
26760 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
26770 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
26780 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
26790 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
267a0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
267b0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
267c0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
267d0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
267e0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
267f0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
26800 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
26810 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
26820 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
26830 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
26840 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
26850 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
26860 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
26870 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
26880 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
26890 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
268a0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
268b0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
268c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
268d0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
268e0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
268f0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
26900 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
26910 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
26920 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
26930 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
26940 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
26950 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
26960 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
26970 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
26980 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
26990 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
269a0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
269b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
269c0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
269d0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
269e0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
269f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
26a00 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
26a10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
26a20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
26a30 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
26a40 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
26a50 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
26a60 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
26a70 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
26a80 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
26a90 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
26aa0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
26ab0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
26ac0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
26ad0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26ae0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
26af0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
26b00 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
26b10 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
26b20 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
26b30 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
26b40 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
26b50 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
26b60 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
26b70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26b80 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26b90 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
26ba0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
26bb0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
26bc0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
26bd0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
26be0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
26bf0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
26c00 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
26c10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26c20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26c30 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
26c40 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
26c50 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
26c60 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
26c70 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
26c80 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
26c90 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
26ca0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
26cb0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
26cc0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
26cd0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
26ce0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
26cf0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
26d00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26d10 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
26d20 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
26d30 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
26d40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26d50 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
26d60 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
26d70 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
26d80 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
26d90 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
26da0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
26db0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
26dc0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
26dd0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26de0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
26df0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
26e00 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
26e10 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
26e20 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26e30 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
26e40 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
26e50 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
26e60 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
26e70 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26e80 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
26e90 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26ea0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
26eb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
26ec0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
26ed0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
26ee0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
26ef0 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
26f00 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
26f10 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
26f20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
26f30 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
26f40 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
26f50 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
26f60 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
26f70 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
26f80 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26f90 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
26fa0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
26fb0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
26fc0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
26fd0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
26fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26ff0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27000 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
27010 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
27020 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
27030 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
27040 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
27050 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
27060 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
27070 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
27080 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
27090 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
270a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
270b0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
270c0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
270d0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
270e0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
270f0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
27100 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
27110 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
27120 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
27130 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27140 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
27150 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
27160 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
27170 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27180 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
27190 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
271a0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
271b0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
271c0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
271d0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
271e0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
271f0 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
27200 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
27210 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
27220 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
27230 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
27240 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
27250 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
27260 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
27270 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
27280 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
27290 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
272a0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
272b0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
272c0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
272d0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
272e0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
272f0 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
27300 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
27310 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
27320 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
27330 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
27340 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
27350 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
27360 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
27370 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
27380 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
27390 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
273a0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
273b0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
273c0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
273d0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
273e0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
273f0 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
27400 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
27410 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
27420 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
27430 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
27440 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
27450 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
27460 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
27470 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
27480 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
27490 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
274a0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
274b0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
274c0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
274d0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
274e0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
274f0 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
27500 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
27510 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
27520 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
27530 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
27540 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
27550 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
27560 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
27570 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
27580 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
27590 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
275a0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
275b0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
275c0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
275d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
275e0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
275f0 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
27600 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
27610 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
27620 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
27630 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
27640 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
27650 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
27660 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
27670 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
27680 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
27690 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
276a0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
276b0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
276c0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
276d0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
276e0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
276f0 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
27700 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
27710 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
27720 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
27730 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
27740 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
27750 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
27760 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
27770 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
27780 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
27790 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
277a0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
277b0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
277c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
277d0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
277e0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
277f0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
27800 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
27810 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
27820 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
27830 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
27840 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
27850 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
27860 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
27870 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
27880 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
27890 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
278a0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
278b0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
278c0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
278d0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
278e0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
278f0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
27900 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
27910 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
27920 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
27930 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
27940 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
27950 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
27960 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
27970 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
27980 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
27990 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
279a0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
279b0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
279c0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
279d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
279e0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
279f0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
27a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
27a10 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
27a20 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
27a30 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
27a40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
27a50 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
27a60 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
27a70 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
27a80 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
27a90 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
27aa0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
27ab0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
27ac0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
27ad0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
27ae0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
27af0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
27b00 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
27b10 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
27b20 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
27b30 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
27b40 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
27b50 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
27b60 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
27b70 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
27b80 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
27b90 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
27ba0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
27bb0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27bc0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
27bd0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
27be0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
27bf0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
27c00 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
27c10 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
27c20 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
27c30 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
27c40 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
27c50 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
27c60 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
27c70 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
27c80 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
27c90 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
27ca0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27cb0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27cc0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
27cd0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
27ce0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
27cf0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27d00 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
27d10 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
27d20 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
27d30 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
27d40 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
27d50 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
27d60 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
27d70 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27d80 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
27d90 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27da0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
27db0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
27dc0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
27dd0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
27de0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
27df0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
27e00 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
27e10 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
27e20 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
27e30 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
27e40 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
27e50 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
27e60 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
27e70 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
27e80 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
27e90 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
27ea0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
27eb0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
27ec0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
27ed0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
27ee0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
27ef0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
27f00 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
27f10 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
27f20 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
27f30 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
27f40 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
27f50 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
27f60 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
27f70 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27f80 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
27f90 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
27fa0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
27fb0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
27fc0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
27fd0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
27fe0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
27ff0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
28000 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28010 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
28020 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
28030 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
28040 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
28050 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
28060 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
28070 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
28080 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28090 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
280a0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
280b0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
280c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
280d0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
280e0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
280f0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
28100 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
28110 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
28120 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
28130 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
28140 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
28150 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
28160 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
28170 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
28180 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
28190 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
281a0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
281b0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
281c0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
281d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
281e0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
281f0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
28200 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
28210 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
28220 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
28230 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
28240 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28250 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
28260 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
28270 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
28280 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
28290 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
282a0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
282b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
282c0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
282d0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
282e0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
282f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
28300 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
28310 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
28320 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28330 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
28340 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
28350 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
28360 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
28370 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
28380 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
28390 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
283a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
283b0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
283c0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
283d0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
283e0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
283f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
28400 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
28410 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
28420 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
28430 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
28440 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
28450 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
28460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
28470 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
28480 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
28490 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
284a0 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
284b0 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
284c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
284d0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
284e0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
284f0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
28500 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
28510 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
28520 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
28530 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
28540 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
28550 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
28560 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
28570 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
28580 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
28590 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
285a0 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
285b0 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
285c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
285d0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
285e0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
285f0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
28600 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
28610 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
28620 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
28630 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
28640 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
28650 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
28660 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
28670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
28680 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
28690 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
286a0 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
286b0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
286c0 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
286d0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
286e0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
286f0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
28700 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
28710 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
28720 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
28730 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
28740 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
28750 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
28760 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
28770 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
28780 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
28790 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
287a0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
287b0 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
287c0 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
287d0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
287e0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
287f0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
28800 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
28810 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
28820 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
28830 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28840 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
28850 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
28860 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
28870 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28880 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
28890 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
288a0 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
288b0 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
288c0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
288d0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
288e0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
288f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28900 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
28910 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
28920 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
28930 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
28940 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
28950 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
28960 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
28970 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
28980 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
28990 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
289a0 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
289b0 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
289c0 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
289d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
289e0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
289f0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
28a00 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
28a10 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28a20 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
28a30 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
28a40 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
28a50 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
28a60 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
28a70 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
28a80 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
28a90 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
28aa0 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
28ab0 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
28ac0 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
28ad0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
28ae0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
28af0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
28b00 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
28b10 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
28b20 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
28b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
28b40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28b50 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28b60 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
28b70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
28b80 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28b90 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
28ba0 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
28bb0 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
28bc0 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
28bd0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
28be0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
28bf0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
28c00 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
28c10 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
28c20 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
28c30 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
28c40 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28c50 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
28c60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28c70 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
28c80 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
28c90 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
28ca0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28cb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
28cc0 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
28cd0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
28ce0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
28cf0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
28d00 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
28d10 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
28d20 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
28d30 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
28d40 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
28d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
28d60 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
28d70 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
28d80 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
28d90 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
28da0 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
28db0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
28dc0 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
28dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28de0 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
28df0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
28e00 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
28e10 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
28e20 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
28e30 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
28e40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
28e50 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
28e60 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
28e70 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
28e80 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
28e90 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
28ea0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
28eb0 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
28ec0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
28ed0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28ee0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28ef0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
28f00 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
28f10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
28f20 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
28f30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
28f40 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
28f50 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
28f60 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
28f70 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
28f80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28f90 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
28fa0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
28fb0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
28fc0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
28fd0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28fe0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
28ff0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29000 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
29010 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29020 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29030 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29040 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29050 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
29060 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
29070 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
29080 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
29090 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
290a0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
290b0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
290c0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
290d0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
290e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
290f0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
29100 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
29110 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
29120 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
29130 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
29140 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
29150 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
29160 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
29170 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
29180 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
29190 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
291a0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
291b0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
291c0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
291d0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
291e0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
291f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
29200 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
29210 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
29220 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
29230 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
29240 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
29250 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
29260 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
29270 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
29280 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
29290 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
292a0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
292b0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
292c0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
292d0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
292e0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
292f0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
29300 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
29310 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
29320 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
29330 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
29340 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
29350 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
29360 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
29370 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
29380 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29390 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
293a0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
293b0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
293c0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
293d0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
293e0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
293f0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
29400 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
29410 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
29420 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
29430 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
29440 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
29450 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
29460 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
29470 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
29480 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
29490 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
294a0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
294b0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
294c0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
294d0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
294e0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
294f0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
29500 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
29510 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
29520 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
29530 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
29540 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
29550 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
29560 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
29570 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
29580 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
29590 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
295a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
295b0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
295c0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
295d0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
295e0 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
295f0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
29600 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
29610 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
29620 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
29630 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
29640 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
29650 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
29660 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
29670 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
29680 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
29690 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
296a0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
296b0 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
296c0 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
296d0 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
296e0 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
296f0 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
29700 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
29710 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
29720 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
29730 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
29740 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
29750 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
29760 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
29770 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
29780 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
29790 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
297a0 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
297b0 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
297c0 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
297d0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
297e0 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
297f0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
29800 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
29810 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
29820 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
29830 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
29840 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
29850 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
29860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
29870 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
29880 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
29890 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
298a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
298b0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
298c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
298d0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
298e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
298f0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
29900 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
29910 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
29920 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
29930 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
29940 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
29950 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
29960 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
29970 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
29980 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
29990 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
299a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
299b0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
299c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
299d0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
299e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
299f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
29a00 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
29a10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29a20 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
29a30 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
29a40 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
29a50 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
29a60 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
29a70 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
29a80 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
29a90 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
29aa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29ab0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
29ac0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
29ad0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
29ae0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
29af0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
29b00 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
29b10 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
29b20 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
29b30 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
29b40 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
29b50 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
29b60 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
29b70 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
29b80 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
29b90 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
29ba0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
29bb0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
29bc0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
29bd0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
29be0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
29bf0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
29c00 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
29c10 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
29c20 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
29c30 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
29c40 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
29c50 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
29c60 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
29c70 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
29c80 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
29c90 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
29ca0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
29cb0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
29cc0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
29cd0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
29ce0 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
29cf0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
29d00 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
29d10 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
29d20 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
29d30 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
29d40 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
29d50 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
29d60 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
29d70 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
29d80 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
29d90 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29da0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29db0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
29dc0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
29dd0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
29de0 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
29df0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
29e00 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
29e10 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
29e20 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
29e30 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
29e40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29e50 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
29e60 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
29e70 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
29e80 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
29e90 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
29ea0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
29eb0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
29ec0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
29ed0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
29ee0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
29ef0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
29f00 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
29f10 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
29f20 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
29f30 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
29f40 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
29f50 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
29f60 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
29f70 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
29f80 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
29f90 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
29fa0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
29fb0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
29fc0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
29fd0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
29fe0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
29ff0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
2a000 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
2a010 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
2a020 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
2a030 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
2a040 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
2a050 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
2a060 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
2a070 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
2a080 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
2a090 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
2a0a0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
2a0b0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
2a0c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
2a0d0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
2a0e0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
2a0f0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
2a100 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
2a110 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2a120 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
2a130 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
2a140 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
2a150 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
2a160 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
2a170 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
2a180 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
2a190 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
2a1a0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2a1b0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
2a1c0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
2a1d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
2a1e0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
2a1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a200 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
2a210 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
2a220 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
2a230 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
2a240 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
2a250 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2a260 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2a270 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
2a280 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
2a290 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
2a2a0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
2a2b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
2a2c0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
2a2d0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
2a2e0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
2a2f0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
2a300 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
2a310 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2a320 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
2a330 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
2a340 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
2a350 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2a360 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2a370 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2a380 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
2a390 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a3a0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
2a3b0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
2a3c0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
2a3d0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
2a3e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a3f0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
2a400 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a410 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
2a420 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a430 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a440 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2a450 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
2a460 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a470 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
2a480 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a490 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
2a4a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a4b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2a4c0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
2a4d0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
2a4e0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
2a4f0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2a500 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
2a510 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a520 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
2a530 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
2a540 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
2a550 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
2a560 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a570 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
2a580 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a590 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
2a5a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a5b0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2a5c0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
2a5d0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
2a5e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a5f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2a600 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
2a610 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a620 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2a630 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
2a640 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a650 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
2a660 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
2a670 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
2a680 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a690 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
2a6a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a6b0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
2a6c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a6d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
2a6e0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
2a6f0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2a700 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
2a710 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
2a720 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
2a730 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
2a740 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
2a750 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
2a760 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
2a770 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
2a780 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2a790 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2a7a0 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2a7b0 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2a7c0 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2a7d0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2a7e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2a7f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2a800 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2a810 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a820 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2a830 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a840 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2a850 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2a860 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a870 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2a880 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2a890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a8a0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2a8b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a8c0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2a8d0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2a8e0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2a8f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a900 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2a910 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2a920 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2a930 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2a940 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a950 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2a960 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2a970 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a980 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2a990 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2a9a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a9b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2a9c0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2a9d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a9e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2a9f0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2aa00 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2aa10 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2aa20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2aa30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2aa40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2aa50 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2aa60 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2aa70 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2aa80 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2aa90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2aaa0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2aab0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2aac0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2aad0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2aae0 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2aaf0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2ab00 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2ab10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ab20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2ab30 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2ab40 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2ab50 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2ab60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab70 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2ab80 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2ab90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2aba0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2abb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2abc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2abd0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2abe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2abf0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2ac00 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2ac10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ac20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2ac30 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2ac40 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2ac50 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2ac60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2ac70 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2ac80 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ac90 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2aca0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2acb0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2acc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2acd0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2ace0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2acf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2ad00 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2ad10 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2ad20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2ad30 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2ad40 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2ad50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2ad60 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2ad70 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2ad80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2ad90 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2ada0 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2adb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2adc0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2add0 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2ade0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2adf0 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  pare Flags.**.**
2ae00 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2ae10 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2ae20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62  flags that can b
2ae30 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  e passed into.**
2ae40 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72   "prepFlags" par
2ae50 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73  ameter of the [s
2ae60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ae70 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  3()] and.** [sql
2ae80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ae90 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e  3()] interfaces.
2aea0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73  .**.** New flags
2aeb0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2aec0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2aed0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2aee0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2aef0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2af00 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  STENT]] ^(<dt>SQ
2af10 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2af20 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  SISTENT</dt>.** 
2af30 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2af40 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2af50 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74  T flag is a hint
2af60 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c   to the query pl
2af70 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  anner.** that th
2af80 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2af90 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74  ment will be ret
2afa0 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67  ained for a long
2afb0 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f   time and.** pro
2afc0 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e  bably reused man
2afd0 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68  y times.)^ ^With
2afe0 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b  out this flag, [
2aff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b000 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  v3()].** and [sq
2b010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b020 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61  v3()] assume tha
2b030 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2b040 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a  tatement will .*
2b050 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f  * be used just o
2b060 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61  nce or at most a
2b070 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74   few times and t
2b080 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
2b090 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2b0a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61  finalize()] rela
2b0b0 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65  tively soon. The
2b0c0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2b0d0 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20  ntation acts.** 
2b0e0 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20  on this hint by 
2b0f0 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65  avoiding the use
2b100 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d   of [lookaside m
2b110 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74  emory] so as not
2b120 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74   to.** deplete t
2b130 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65  he limited store
2b140 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
2b150 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72  mory. Future ver
2b160 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69  sions of.** SQLi
2b170 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68  te may act on th
2b180 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e  is hint differen
2b190 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  tly..** </dl>.*/
2b1a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b1b0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2b1c0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2b1d0 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2b1e0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2b1f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2b200 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2b210 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2b220 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2b230 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2b240 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2b250 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2b260 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2b270 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2b280 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2b290 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2b2a0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2b2b0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2b2c0 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2b2d0 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2b2e0 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2b2f0 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2b300 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2b310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b320 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2b330 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2b340 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2b350 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b360 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2b370 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b380 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2b390 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2b3a0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2b3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b3c0 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2b3d0 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2b3e0 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2b3f0 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2b400 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2b410 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2b420 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2b430 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2b440 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2b450 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2b460 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2b470 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2b480 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2b490 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2b4a0 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2b4b0 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2b4c0 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2b4d0 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2b4e0 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2b4f0 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2b500 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2b510 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2b520 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2b530 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2b540 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2b550 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b560 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2b570 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2b580 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2b590 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2b5a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2b5b0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2b5c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2b5d0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2b5e0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2b5f0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2b600 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2b610 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2b620 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2b630 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2b640 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2b650 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2b660 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2b670 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2b680 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2b690 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2b6a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b6b0 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2b6c0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2b6d0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2b6e0 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2b6f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b700 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b710 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b720 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2b730 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2b740 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2b750 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2b760 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2b770 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2b780 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2b790 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2b7a0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2b7b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b7c0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2b7d0 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2b7e0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2b7f0 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2b800 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2b810 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2b820 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2b830 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2b840 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2b850 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2b860 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2b870 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2b880 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2b890 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2b8a0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2b8b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2b8c0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2b8d0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2b8e0 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2b8f0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2b900 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2b910 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2b920 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2b930 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2b940 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2b950 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2b960 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2b970 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2b980 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2b990 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2b9a0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2b9b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2b9c0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2b9d0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2b9e0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2b9f0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2ba00 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2ba10 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2ba20 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2ba30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2ba40 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2ba50 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2ba60 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2ba70 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2ba80 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2ba90 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2baa0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2bab0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2bac0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2bad0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2bae0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2baf0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2bb00 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2bb10 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2bb20 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2bb30 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2bb40 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2bb50 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2bb60 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2bb70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2bb80 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2bb90 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2bba0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2bbb0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2bbc0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2bbd0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2bbe0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2bbf0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2bc00 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2bc10 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2bc20 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2bc30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2bc40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bc50 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2bc60 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2bc70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bc80 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2bc90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2bca0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2bcb0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2bcc0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2bcd0 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2bce0 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2bcf0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2bd00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bd10 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2bd20 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2bd30 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2bd40 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2bd50 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2bd60 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2bd70 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2bd80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bd90 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2bda0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2bdb0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2bdc0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2bdd0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2bde0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2bdf0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2be00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2be10 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2be20 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2be30 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2be40 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2be50 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2be60 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2be70 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2be80 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2be90 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2bea0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2beb0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2bec0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2bed0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2bee0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2bef0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2bf00 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2bf10 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2bf20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2bf30 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2bf40 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2bf50 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2bf60 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2bf70 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2bf80 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2bf90 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2bfa0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2bfb0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2bfc0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2bfd0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2bfe0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2bff0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2c000 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2c010 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2c020 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2c030 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2c040 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2c050 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2c060 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2c070 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2c080 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2c090 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2c0a0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2c0b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c0c0 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2c0d0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2c0e0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2c0f0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2c100 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2c110 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2c120 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2c130 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2c140 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2c150 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2c160 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2c170 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2c180 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2c190 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2c1a0 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2c1b0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2c1c0 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2c1d0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2c1e0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2c1f0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2c200 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2c210 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2c220 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2c230 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2c240 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2c250 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2c260 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2c270 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2c280 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2c290 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2c2a0 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2c2b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2c2c0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2c2d0 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2c2e0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2c2f0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2c300 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2c310 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2c320 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2c330 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2c340 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2c350 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2c360 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2c370 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2c380 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2c390 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c3a0 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2c3b0 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2c3c0 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2c3d0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2c3e0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2c3f0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2c400 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ed..** </li>.**.
2c410 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70  ** <p>^sqlite3_p
2c420 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66  repare_v3() diff
2c430 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ers from sqlite3
2c440 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e  _prepare_v2() on
2c450 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20  ly in having.** 
2c460 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c  the extra prepFl
2c470 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77  ags parameter, w
2c480 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72  hich is a bit ar
2c490 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  ray consisting o
2c4a0 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  f zero or.** mor
2c4b0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
2c4c0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2c4d0 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41  ENT|SQLITE_PREPA
2c4e0 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54  RE_*] flags.  ^T
2c4f0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
2c500 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72  epare_v2() inter
2c510 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74  face works exact
2c520 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ly the same as.*
2c530 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2c540 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65  e_v3() with a ze
2c550 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ro prepFlags par
2c560 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ameter..** </ol>
2c570 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c580 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2c590 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c5a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c5b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c5c0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2c5d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c5e0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2c5f0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2c600 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2c610 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2c620 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2c630 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2c640 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c650 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c660 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c670 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c680 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c690 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c6a0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c6b0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c6c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2c6d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c6e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c6f0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2c710 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c720 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2c730 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c740 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c750 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c760 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c770 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c780 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c790 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c7a0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c7b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c7c0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c7d0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c7e0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c7f0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c800 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c810 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2c820 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c830 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c850 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c860 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c870 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c880 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c890 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c8a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c8b0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c8c0 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2c8d0 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2c8e0 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2c8f0 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2c900 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2c910 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c920 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c930 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c940 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2c950 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c960 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c970 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c980 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c990 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2c9a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c9b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c9c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c9d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2c9e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c9f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2ca00 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2ca10 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ca20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ca30 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ca40 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ca50 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ca60 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ca70 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ca80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ca90 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2caa0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2cab0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2cac0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2cad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cae0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2caf0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2cb00 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2cb10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2cb20 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2cb30 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2cb40 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2cb50 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2cb60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cb70 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2cb80 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2cb90 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2cba0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2cbb0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2cbc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cbd0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2cbe0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2cbf0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2cc00 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2cc10 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2cc20 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2cc30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2cc40 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2cc50 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2cc60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2cc70 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2cc80 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2cc90 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2cca0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ccb0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ccc0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ccd0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2cce0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2ccf0 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2cd00 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2cd10 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2cd20 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cd30 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cd40 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cd50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cd60 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2cd70 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cd80 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cd90 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cda0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cdb0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2cdc0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2cdd0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2cde0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2cdf0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2ce00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ce10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2ce20 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2ce30 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2ce40 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2ce50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ce60 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2ce70 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2ce80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2ce90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cea0 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2ceb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2cec0 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2ced0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2cee0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2cef0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2cf00 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2cf10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2cf20 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2cf30 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2cf40 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2cf50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cf60 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2cf70 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2cf80 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2cf90 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2cfa0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2cfb0 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2cfc0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2cfd0 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2cfe0 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2cff0 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2d000 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2d010 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2d020 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2d030 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2d040 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2d050 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2d060 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2d070 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2d080 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2d090 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2d0a0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2d0b0 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2d0c0 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2d0d0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d0e0 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2d0f0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2d100 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2d110 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2d120 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2d130 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2d140 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2d150 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2d160 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2d170 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2d180 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2d190 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2d1a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2d1b0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2d1c0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2d1d0 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2d1e0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2d1f0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2d200 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2d210 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2d220 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2d230 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2d240 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2d250 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2d260 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2d270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2d280 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2d290 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2d2a0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2d2b0 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2d2c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2d2d0 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2d2e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2d2f0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2d300 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2d310 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2d320 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2d330 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2d340 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2d350 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d360 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2d370 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2d380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2d390 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2d3a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2d3b0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2d3c0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2d3d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d3e0 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2d3f0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d400 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d410 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d420 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2d430 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2d440 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2d450 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2d460 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d480 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d490 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2d4a0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2d4b0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2d4c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2d4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d4e0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2d4f0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2d500 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2d510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d520 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2d530 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2d540 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2d550 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2d560 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2d570 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2d580 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2d590 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2d5a0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2d5b0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2d5c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d5d0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2d5e0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2d5f0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2d600 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2d610 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2d620 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2d630 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2d640 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2d650 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2d660 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2d670 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2d680 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2d690 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2d6a0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2d6b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2d6c0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2d6d0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2d6e0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2d6f0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2d700 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2d710 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2d720 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2d730 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2d740 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2d750 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2d760 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2d770 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2d780 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2d790 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2d7a0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2d7b0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2d7c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d7d0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2d7e0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2d7f0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2d800 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2d810 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2d820 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2d830 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2d840 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2d850 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2d860 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2d870 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2d880 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2d890 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2d8a0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2d8b0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2d8c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2d8d0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2d8e0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2d8f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2d900 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2d910 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2d920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2d930 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2d940 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2d950 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d960 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d970 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2d980 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d990 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2d9a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d9b0 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2d9c0 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2d9d0 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2d9e0 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2d9f0 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2da00 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2da10 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2da20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2da30 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2da40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2da50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2da60 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2da70 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2da80 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2da90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2daa0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2dab0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2dac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2dad0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2dae0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2daf0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2db00 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2db10 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2db20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2db30 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2db40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2db50 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2db60 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2db70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2db80 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2db90 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2dba0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2dbb0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2dbc0 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2dbd0 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2dbe0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2dbf0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2dc00 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2dc10 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2dc20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2dc30 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2dc40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2dc50 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2dc60 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2dc70 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2dc80 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2dc90 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2dca0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2dcb0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2dcc0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2dcd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2dce0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2dcf0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2dd00 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2dd10 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2dd20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2dd30 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2dd40 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2dd50 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2dd60 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2dd70 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2dd80 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2dd90 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2dda0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2ddb0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2ddc0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2ddd0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2dde0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2ddf0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2de00 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2de10 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2de20 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2de30 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2de40 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2de50 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2de60 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2de70 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2de80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2de90 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2dea0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2deb0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2dec0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2ded0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2dee0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2def0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2df00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2df10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2df20 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2df30 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2df40 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2df50 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2df60 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2df70 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2df80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2df90 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2dfa0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2dfb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2dfc0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2dfd0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2dfe0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2dff0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2e000 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2e010 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2e020 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2e030 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2e040 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2e050 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2e060 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2e070 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e080 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2e090 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2e0a0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2e0b0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2e0c0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2e0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2e0e0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2e0f0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2e100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2e110 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2e120 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2e130 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2e140 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e150 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2e160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e170 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2e180 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2e190 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2e1a0 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2e1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2e1c0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2e1d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e1e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2e1f0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2e200 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2e210 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2e220 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2e230 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2e240 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2e250 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2e260 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e270 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2e280 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2e290 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2e2a0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e2b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2e2c0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2e2d0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2e2e0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2e2f0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2e300 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2e310 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2e320 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2e330 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2e340 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2e350 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2e360 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2e370 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e380 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2e390 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e3a0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2e3b0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2e3c0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2e3d0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2e3e0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2e3f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e400 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2e410 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2e420 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2e430 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2e440 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2e450 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2e460 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2e470 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2e480 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2e490 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2e4a0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2e4b0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e4d0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2e4e0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2e4f0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2e500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e510 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2e520 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2e530 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2e540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e550 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2e560 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e570 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2e580 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2e590 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e5a0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2e5b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e5c0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2e5d0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2e5e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e5f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2e600 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e610 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2e620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2e630 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2e640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2e650 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2e660 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2e670 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2e680 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2e690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2e6a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2e6b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2e6c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2e6d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e6e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2e6f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e700 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2e710 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2e720 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2e730 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2e740 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2e750 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2e760 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2e770 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2e780 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2e790 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2e7a0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2e7b0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2e7c0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2e7d0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2e7e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2e7f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2e810 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2e820 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e830 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e840 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2e850 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2e860 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2e870 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e880 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2e890 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2e8a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2e8b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2e8c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2e8d0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2e8e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2e8f0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2e900 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e910 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2e920 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e930 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2e940 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e950 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2e960 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2e970 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2e980 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2e990 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e9a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2e9b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2e9c0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2e9d0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2e9e0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2e9f0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2ea00 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2ea10 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2ea20 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2ea30 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ea40 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2ea50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2ea60 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2ea70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ea80 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2ea90 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2eaa0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2eab0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2eac0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2ead0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2eae0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2eaf0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2eb00 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2eb10 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2eb20 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2eb30 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2eb40 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2eb50 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2eb60 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2eb70 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2eb80 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2eb90 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2eba0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2ebb0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2ebc0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2ebd0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2ebe0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2ebf0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2ec00 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2ec10 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2ec20 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2ec30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ec40 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2ec50 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2ec60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ec70 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2ec80 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ec90 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2eca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ecb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2ecc0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2ecd0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2ece0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2ecf0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2ed00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2ed10 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ed20 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2ed30 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2ed40 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2ed50 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2ed60 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2ed70 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2ed80 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2ed90 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2eda0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2edb0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2edc0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2edd0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2ede0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2edf0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2ee00 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2ee10 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2ee20 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2ee30 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2ee40 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2ee50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ee60 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2ee70 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2ee80 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2ee90 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2eea0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2eeb0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2eec0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2eed0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2eee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2eef0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2ef00 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2ef10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2ef20 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2ef30 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2ef40 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2ef50 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2ef60 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2ef70 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2ef80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2ef90 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2efa0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2efb0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2efc0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2efd0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2efe0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2eff0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2f000 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2f010 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2f020 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2f030 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2f040 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2f050 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2f060 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2f070 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2f080 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2f090 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f0a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2f0b0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2f0c0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2f0d0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2f0e0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2f0f0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2f100 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2f110 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2f120 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2f130 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2f140 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f150 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f160 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2f170 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2f180 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2f190 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2f1a0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2f1b0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2f1c0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2f1d0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2f1e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f1f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2f200 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2f210 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2f220 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2f230 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2f240 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2f250 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2f260 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2f270 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2f280 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f290 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2f2a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f2b0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2f2c0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2f2d0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2f2e0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2f2f0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2f300 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2f310 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2f320 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2f330 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2f340 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2f350 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2f360 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2f370 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2f380 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f390 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2f3a0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2f3b0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2f3c0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2f3d0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2f3e0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2f3f0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2f400 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2f410 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2f420 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2f430 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f440 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2f450 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2f460 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2f470 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2f480 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2f490 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2f4a0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2f4b0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2f4c0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2f4d0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2f4e0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2f4f0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2f500 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2f510 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2f520 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2f530 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f540 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2f550 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2f560 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2f570 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2f580 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2f590 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2f5a0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2f5b0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2f5c0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f5d0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2f5e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2f5f0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2f600 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2f610 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2f620 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2f630 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2f640 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2f650 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2f660 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2f670 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2f680 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2f690 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2f6a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2f6b0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2f6c0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2f6d0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2f6e0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2f6f0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2f700 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2f710 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2f720 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2f730 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2f740 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2f750 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2f760 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2f770 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2f780 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2f790 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2f7a0 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2f7b0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2f7c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2f7d0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2f7e0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2f7f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2f800 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2f810 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f820 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2f830 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2f850 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2f860 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2f870 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2f880 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2f890 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2f8a0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2f8b0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2f8c0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2f8d0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2f8e0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2f8f0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2f900 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2f910 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2f920 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2f930 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2f940 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2f950 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2f960 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2f970 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2f980 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2f990 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2f9a0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2f9b0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2f9c0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2f9d0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2f9e0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2f9f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2fa00 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
2fa10 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
2fa20 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
2fa30 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
2fa40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2fa50 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
2fa60 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
2fa70 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
2fa80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2fa90 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
2faa0 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
2fab0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
2fac0 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
2fad0 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
2fae0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2faf0 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
2fb00 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
2fb10 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
2fb20 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
2fb30 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
2fb40 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
2fb50 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
2fb60 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
2fb70 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
2fb80 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
2fb90 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
2fba0 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
2fbb0 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2fbc0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
2fbd0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
2fbe0 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
2fbf0 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
2fc00 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
2fc10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2fc20 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2fc30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2fc40 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2fc50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2fc60 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2fc70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2fc80 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2fc90 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2fca0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2fcb0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2fcc0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2fcd0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2fce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2fcf0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2fd00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2fd10 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2fd20 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2fd30 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2fd40 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2fd50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fd60 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2fd70 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2fd80 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2fd90 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2fda0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2fdb0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2fdc0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2fdd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fde0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2fdf0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2fe00 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2fe10 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2fe20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fe30 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2fe40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2fe50 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2fe60 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2fe70 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2fe80 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2fe90 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2fea0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2feb0 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2fec0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2fed0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2fee0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2fef0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2ff00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2ff10 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2ff20 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2ff30 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2ff40 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2ff50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2ff60 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2ff70 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2ff80 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2ff90 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2ffa0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2ffb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2ffc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ffd0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2ffe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2fff0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
30000 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
30010 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30020 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
30030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30050 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30060 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
30070 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
30080 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
30090 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
300a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
300b0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
300c0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
300d0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
300e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
300f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
30100 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30110 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
30120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30130 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
30140 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
30150 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30160 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
30170 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
30180 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
30190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
301a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
301b0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
301c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
301d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
301e0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
301f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30200 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30210 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30220 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30230 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30240 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30250 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
30260 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
30270 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30280 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
30290 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
302a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
302b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
302c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
302d0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
302e0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
302f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30300 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
30310 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
30320 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
30330 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
30340 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
30350 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
30360 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
30380 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
30390 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
303a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
303b0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
303c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
303d0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
303e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
303f0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
30400 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
30410 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30420 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
30430 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
30440 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
30450 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
30460 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
30470 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
30480 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
30490 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
304a0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
304b0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
304c0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
304d0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
304e0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
304f0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
30500 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
30510 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
30520 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
30530 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
30540 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
30550 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
30560 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
30570 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
30580 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
30590 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
305a0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
305b0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
305c0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
305d0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
305e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
305f0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
30600 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
30610 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
30620 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
30630 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
30640 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
30650 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30660 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
30670 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
30680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30690 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
306a0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
306b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
306c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
306d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
306e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
306f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
30700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30710 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
30720 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
30730 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30740 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
30750 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30760 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
30770 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30780 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
30790 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
307a0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
307b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
307c0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
307d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
307e0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
307f0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
30800 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
30810 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
30820 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
30830 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
30840 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
30850 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
30860 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
30870 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
30880 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
30890 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
308a0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
308b0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
308c0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
308d0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
308e0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
308f0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
30900 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
30910 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
30920 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
30930 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
30940 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
30950 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
30960 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
30970 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
30980 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
30990 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
309a0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
309b0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
309c0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
309d0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
309e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
309f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
30a00 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
30a10 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
30a20 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
30a30 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
30a40 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
30a50 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
30a60 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
30a70 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
30a80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a90 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
30aa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30ab0 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
30ac0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30ad0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30ae0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
30af0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30b00 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
30b10 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
30b20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30b30 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
30b40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30b50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30b60 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30b70 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
30b80 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
30b90 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
30ba0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
30bb0 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
30bc0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30bd0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
30be0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
30bf0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
30c00 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
30c10 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
30c20 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
30c30 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
30c40 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
30c50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
30c60 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30c70 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
30c80 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
30c90 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
30ca0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
30cb0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
30cc0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
30cd0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
30ce0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
30cf0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
30d00 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
30d10 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
30d20 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
30d30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
30d40 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
30d50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
30d60 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
30d70 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30d80 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30d90 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30da0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30db0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
30dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30dd0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30de0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30df0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30e00 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
30e10 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
30e20 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
30e30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30e40 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
30e50 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
30e60 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
30e70 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30e80 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
30e90 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
30ea0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
30eb0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
30ec0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
30ed0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30ee0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
30ef0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30f00 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
30f10 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
30f20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
30f30 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
30f40 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
30f50 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
30f60 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
30f70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30f80 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
30f90 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
30fa0 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
30fb0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30fc0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
30fd0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
30fe0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
30ff0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
31000 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
31010 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
31020 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
31030 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
31040 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
31050 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31060 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
31070 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
31080 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
31090 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
310a0 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
310b0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
310c0 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
310d0 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
310e0 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
310f0 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
31100 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
31110 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
31120 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
31130 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
31140 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
31150 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
31160 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
31170 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
31180 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
31190 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
311a0 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
311b0 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
311c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
311d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
311e0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
311f0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
31200 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31210 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31220 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
31230 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31240 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31250 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31260 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31270 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31280 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
31290 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
312a0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
312b0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
312c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
312d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
312e0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
312f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31300 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
31310 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
31320 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
31330 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
31340 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
31350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
31360 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
31370 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
31380 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
31390 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
313a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
313b0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
313c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
313d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
313e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
313f0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
31400 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
31410 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
31420 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
31430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
31440 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
31450 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
31460 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
31470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31480 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
31490 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
314a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
314b0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
314c0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
314d0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
314e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
314f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31500 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
31510 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
31520 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
31530 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
31540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31550 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31560 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
31570 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
31580 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
31590 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
315a0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
315b0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
315c0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
315d0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
315e0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
315f0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
31600 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
31610 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
31620 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
31630 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
31640 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
31650 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
31660 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
31670 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
31680 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
31690 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
316a0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
316b0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
316c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
316d0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
316e0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
316f0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
31700 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
31710 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
31720 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31730 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
31740 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31750 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
31760 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31770 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31780 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
31790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
317a0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
317b0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
317c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
317d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
317e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
317f0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
31800 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
31810 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31820 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
31830 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
31840 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
31850 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
31860 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
31870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
31880 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
31890 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
318a0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
318b0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
318c0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
318d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
318e0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
318f0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
31900 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
31910 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
31920 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
31930 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
31940 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
31950 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
31960 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31970 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
31980 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31990 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
319a0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
319b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
319c0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
319d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
319e0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
319f0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
31a00 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
31a10 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
31a20 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
31a30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31a40 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
31a50 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
31a60 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
31a70 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
31a80 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
31a90 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
31aa0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
31ab0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
31ac0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
31ad0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
31ae0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
31af0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31b00 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
31b10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
31b20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
31b30 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
31b40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31b50 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
31b60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31b70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
31b80 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
31b90 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
31ba0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
31bb0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
31bc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31bd0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31be0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
31bf0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
31c00 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
31c10 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
31c20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
31c30 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
31c40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31c50 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
31c60 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
31c70 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
31c80 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
31c90 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
31ca0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
31cb0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
31cc0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
31cd0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
31ce0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31cf0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
31d00 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
31d10 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
31d20 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
31d30 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
31d40 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
31d50 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
31d60 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
31d70 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
31d80 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
31d90 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
31da0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
31db0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
31dc0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
31dd0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
31de0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
31df0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
31e00 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
31e10 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
31e20 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
31e30 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
31e40 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
31e50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
31e60 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
31e70 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
31e80 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
31e90 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
31ea0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
31eb0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
31ec0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31ed0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
31ee0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
31ef0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
31f00 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
31f10 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
31f20 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
31f30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
31f40 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
31f50 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
31f60 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
31f70 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
31f80 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
31f90 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
31fa0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
31fb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
31fc0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
31fd0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
31fe0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
31ff0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32000 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
32010 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
32020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
32030 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
32040 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32050 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32060 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32070 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
32080 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
32090 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
320a0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
320b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
320c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
320d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
320e0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
320f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32100 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
32110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
32120 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
32130 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32140 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32150 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
32160 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
32170 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
32180 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
32190 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
321a0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
321b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
321c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
321d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
321e0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
321f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32200 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
32210 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
32220 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
32230 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
32240 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
32250 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
32260 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
32270 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
32280 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
32290 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
322a0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
322b0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
322c0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
322d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
322e0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
322f0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
32300 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
32310 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
32320 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
32330 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
32340 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
32350 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
32360 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
32370 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
32380 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
32390 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
323a0 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
323b0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
323c0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
323d0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
323e0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
323f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
32400 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
32410 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
32420 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
32430 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
32440 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
32450 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
32460 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
32470 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
32480 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
32490 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
324a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
324b0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
324c0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
324d0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
324e0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
324f0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
32500 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
32510 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
32520 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
32530 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
32540 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
32550 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
32560 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
32570 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
32580 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
32590 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
325a0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
325b0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
325c0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
325d0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
325e0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
325f0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
32600 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
32610 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
32620 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
32630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
32640 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
32650 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
32660 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32670 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
32680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32690 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
326a0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
326b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
326c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
326d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
326e0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
326f0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
32700 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
32710 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
32720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
32730 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32740 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
32750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32760 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
32770 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32780 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
32790 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
327a0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
327b0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
327c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
327d0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
327e0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
327f0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
32800 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
32810 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
32820 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
32830 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
32840 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
32850 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
32860 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
32870 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
32880 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
32890 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
328a0 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
328b0 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
328c0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
328d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
328e0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
328f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32900 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
32910 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
32920 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
32930 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
32940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32950 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
32960 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
32970 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
32980 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
32990 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
329a0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
329b0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
329c0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
329d0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
329e0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
329f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
32a00 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
32a10 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
32a20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
32a30 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
32a40 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
32a50 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
32a60 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
32a70 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
32a80 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
32a90 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
32aa0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
32ab0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
32ac0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
32ad0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
32ae0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
32af0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
32b00 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
32b10 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
32b20 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
32b30 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
32b40 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
32b50 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
32b60 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
32b70 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
32b80 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
32b90 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
32ba0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
32bb0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
32bc0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
32bd0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
32be0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
32bf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32c00 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
32c10 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
32c20 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
32c30 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
32c40 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
32c50 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
32c60 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
32c70 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
32c80 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
32c90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
32ca0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
32cb0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
32cc0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
32cd0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
32ce0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
32cf0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
32d00 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
32d10 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
32d20 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
32d30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32d40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
32d50 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
32d60 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
32d70 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
32d80 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
32d90 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
32da0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
32db0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
32dc0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
32dd0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
32de0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
32df0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
32e00 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
32e10 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
32e20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
32e30 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
32e40 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
32e50 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
32e60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
32e70 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
32e80 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
32e90 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
32ea0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
32eb0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
32ec0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
32ed0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
32ee0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
32ef0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
32f00 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
32f10 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
32f20 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
32f30 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
32f40 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
32f50 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
32f60 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
32f70 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
32f80 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
32f90 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
32fa0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32fb0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
32fc0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
32fd0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
32fe0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
32ff0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
33000 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
33010 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
33020 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
33030 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
33040 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
33050 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
33060 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
33070 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
33080 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
33090 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
330a0 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
330b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
330c0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
330d0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
330e0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
330f0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
33100 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
33110 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
33120 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
33130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33140 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
33150 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
33160 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
33170 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
33180 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
33190 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
331a0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
331b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
331c0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
331d0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
331e0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
331f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33200 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
33210 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
33220 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
33230 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
33240 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
33250 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
33260 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
33270 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
33280 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
33290 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
332a0 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
332b0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
332c0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
332d0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
332e0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
332f0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
33300 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
33310 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
33320 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
33330 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
33340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33350 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
33360 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
33370 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
33380 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
33390 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
333a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
333b0 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
333c0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
333d0 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
333e0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
333f0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
33400 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
33410 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
33420 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
33430 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
33440 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
33450 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
33460 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
33470 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
33480 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
33490 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
334a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
334b0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
334c0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
334d0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
334e0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
334f0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
33500 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
33510 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
33520 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
33530 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
33540 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
33550 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
33560 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
33570 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
33580 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
33590 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
335a0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
335b0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
335c0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
335d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
335e0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
335f0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
33600 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
33610 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
33620 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
33630 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
33640 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
33650 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33660 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
33670 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
33680 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
33690 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
336a0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
336b0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
336c0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
336d0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
336e0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
336f0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
33700 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
33710 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
33720 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
33730 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
33740 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
33750 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
33760 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
33770 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
33780 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33790 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
337a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
337b0 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
337c0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
337d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
337e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
337f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
33800 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
33810 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
33820 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
33830 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
33840 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
33850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
33860 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
33870 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
33880 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
33890 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
338a0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
338b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
338c0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
338d0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
338e0 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
338f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33910 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
33920 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
33940 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
33950 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
33960 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
33970 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
33980 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
33990 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
339a0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
339b0 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
339c0 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
339d0 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
339e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
339f0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
33a00 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
33a10 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
33a20 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
33a30 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
33a40 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
33a50 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33a60 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
33a70 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
33a80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
33a90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33aa0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
33ab0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
33ac0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
33ad0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33ae0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
33af0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
33b00 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
33b10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33b20 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
33b30 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
33b40 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
33b50 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
33b60 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
33b70 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
33b80 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
33b90 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
33ba0 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
33bb0 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
33bc0 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
33bd0 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
33be0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
33bf0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
33c00 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
33c10 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
33c20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
33c30 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
33c40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
33c50 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
33c60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33c80 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
33c90 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
33ca0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
33cb0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
33cc0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
33cd0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
33ce0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
33cf0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
33d00 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
33d10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33d20 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
33d30 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
33d40 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
33d50 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
33d60 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
33d70 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
33d80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33d90 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
33da0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
33db0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
33dc0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
33dd0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
33de0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
33df0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
33e00 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
33e10 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
33e20 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
33e30 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
33e40 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
33e50 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
33e60 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
33e70 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
33e80 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
33e90 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
33ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33eb0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
33ec0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
33ed0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33ee0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
33ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
33f00 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
33f10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
33f20 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
33f30 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
33f40 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
33f50 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
33f60 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
33f70 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
33f80 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
33f90 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
33fa0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
33fb0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
33fc0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
33fd0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33fe0 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
33ff0 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
34000 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
34010 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
34020 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
34030 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
34050 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
34060 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
34070 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
34090 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
340a0 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
340b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
340c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
340d0 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
340e0 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
340f0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
34100 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34110 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
34120 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
34130 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
34140 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34150 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34160 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
34170 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
34180 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34190 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
341a0 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
341b0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
341c0 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
341d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
341e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
341f0 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
34200 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
34210 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
34220 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
34230 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34240 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
34250 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
34260 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34270 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34290 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
342a0 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
342b0 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
342c0 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
342d0 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
342e0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
342f0 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
34300 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
34310 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
34320 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
34330 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
34340 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
34350 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34360 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
34370 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
34380 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
34390 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
343a0 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
343b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
343c0 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
343d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
343e0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
343f0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
34400 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
34410 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
34420 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
34430 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
34440 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
34450 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
34460 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
34470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34480 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
34490 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
344a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
344b0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
344c0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
344d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
344e0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
344f0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
34500 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
34510 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
34520 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
34530 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
34540 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
34550 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
34560 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
34570 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
34580 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
34590 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
345a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
345b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
345c0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
345d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
345e0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
345f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
34600 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
34610 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
34620 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
34630 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
34640 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
34650 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
34660 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
34670 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
34680 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
34690 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
346a0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
346b0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
346c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
346d0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
346e0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
346f0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
34700 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
34710 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34720 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
34730 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
34740 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
34750 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
34760 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
34770 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34780 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
34790 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
347a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
347b0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
347c0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
347d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
347e0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
347f0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34800 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
34810 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
34820 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34830 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
34840 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
34850 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
34860 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
34870 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
34880 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
34890 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
348a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
348b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
348c0 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
348d0 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
348e0 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
348f0 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
34900 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
34910 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
34920 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
34930 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
34940 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
34950 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
34960 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
34970 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
34980 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
34990 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
349a0 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
349b0 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
349c0 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
349d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
349e0 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
349f0 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
34a00 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
34a10 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
34a20 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
34a30 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
34a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34a50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34a60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34a70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
34a80 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
34a90 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
34aa0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
34ab0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
34ac0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
34ad0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
34ae0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
34af0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
34b00 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
34b10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
34b20 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
34b30 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
34b40 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
34b50 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
34b60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
34b70 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
34b80 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
34b90 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
34ba0 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
34bb0 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
34bc0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
34bd0 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
34be0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
34bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34c00 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
34c10 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
34c20 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
34c30 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
34c40 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
34c50 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
34c60 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
34c70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
34c80 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
34c90 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
34ca0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
34cb0 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
34cc0 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
34cd0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
34ce0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
34cf0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
34d00 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
34d10 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34d20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
34d30 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
34d40 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
34d50 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
34d60 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
34d70 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
34d80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
34d90 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
34da0 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
34db0 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
34dc0 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
34dd0 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
34de0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34df0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
34e00 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34e10 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
34e20 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
34e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34e40 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
34e50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34e60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
34e70 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
34e80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34e90 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
34ea0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
34eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34ec0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
34ed0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
34ee0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
34ef0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34f00 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
34f10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34f20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
34f30 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34f40 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
34f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
34f60 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
34f70 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
34f80 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
34f90 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34fa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34fb0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34fc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34fd0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34fe0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34ff0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
35000 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
35010 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35020 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
35030 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
35040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35050 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
35060 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
35070 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35080 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
35090 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
350a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
350b0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
350c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
350d0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
350e0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
350f0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
35100 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
35110 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35120 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
35130 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
35140 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
35150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35160 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
35170 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
35180 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
35190 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
351a0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
351b0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
351c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
351d0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
351e0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
351f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
35200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35210 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
35220 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
35230 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
35240 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35250 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35260 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
35270 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35280 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
35290 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
352a0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
352b0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
352c0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
352d0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
352e0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
352f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35300 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35320 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
35330 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
35340 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
35350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
35360 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
35370 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
35380 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
35390 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
353a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
353b0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
353c0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
353d0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
353e0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
353f0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
35400 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
35410 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
35420 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
35430 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
35440 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
35450 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
35460 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
35470 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35480 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
35490 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
354a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
354b0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
354c0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
354d0 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
354e0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
354f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
35500 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
35510 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
35520 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
35530 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
35540 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35550 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
35560 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35570 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35580 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
35590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
355a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
355b0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
355c0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
355d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
355e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
355f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
35600 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
35610 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
35620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
35630 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
35640 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
35650 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
35660 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
35670 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
35680 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
35690 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
356a0 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
356b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
356c0 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
356d0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
356e0 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
356f0 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
35700 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
35710 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
35720 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
35730 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
35740 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
35750 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
35760 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
35770 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
35780 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
35790 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
357a0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
357b0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
357c0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
357d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
357e0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
357f0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
35800 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
35810 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
35820 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
35830 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
35840 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
35850 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
35860 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
35870 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
35880 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
35890 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
358a0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
358b0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
358c0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
358d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
358e0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
358f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35900 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
35910 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
35920 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
35930 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
35940 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
35950 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
35960 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
35970 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
35980 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
35990 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
359a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
359b0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
359c0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
359d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
359e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
359f0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
35a00 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
35a10 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
35a20 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
35a30 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
35a40 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
35a50 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
35a60 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
35a70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
35a80 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
35a90 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
35aa0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
35ab0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35ac0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35ad0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35ae0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
35af0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
35b00 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
35b10 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
35b20 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
35b30 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
35b40 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
35b50 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
35b60 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35b70 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35b80 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35b90 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35ba0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35bb0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35bc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
35bd0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
35be0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
35bf0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
35c00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
35c10 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
35c20 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
35c30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
35c40 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35c50 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35c60 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
35c70 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
35c80 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35c90 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
35ca0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
35cb0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
35cc0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
35cd0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
35ce0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
35cf0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
35d00 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
35d10 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
35d20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
35d30 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
35d40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
35d50 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
35d60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35d70 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
35d80 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
35d90 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
35da0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
35db0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
35dc0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
35dd0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
35de0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
35df0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35e00 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
35e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35e20 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
35e30 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
35e40 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
35e50 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
35e60 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
35e70 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
35e80 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
35e90 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
35ea0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35eb0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
35ec0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
35ed0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35ee0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
35ef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35f00 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
35f10 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
35f20 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
35f30 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
35f40 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
35f50 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35f60 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
35f70 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
35f80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
35f90 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
35fa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
35fb0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
35fc0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
35fd0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
35fe0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
35ff0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
36000 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
36010 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
36020 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
36030 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
36040 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
36050 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
36060 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
36070 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
36080 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36090 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
360a0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
360b0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
360c0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
360d0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
360e0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
360f0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
36100 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
36110 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
36120 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
36130 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
36140 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
36150 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
36160 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
36170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
36180 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
36190 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
361a0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
361b0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
361c0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
361d0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
361e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
361f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36210 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36220 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
36230 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
36240 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36250 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
36260 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36270 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36280 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
36290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
362a0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
362b0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
362c0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
362d0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
362e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
362f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
36300 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
36310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36320 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
36330 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
36340 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
36350 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
36360 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
36370 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
36380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
36390 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
363a0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
363b0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
363c0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
363d0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
363e0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
363f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36400 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
36410 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
36420 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
36430 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
36440 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
36450 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
36460 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
36470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36480 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
36490 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
364a0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
364b0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
364c0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
364d0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
364e0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
364f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
36500 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
36510 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
36520 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
36530 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
36540 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
36550 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
36560 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
36570 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
36580 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
36590 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
365a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
365b0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
365c0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
365d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
365e0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
365f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
36600 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
36610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36620 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
36630 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
36640 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
36650 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
36660 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
36670 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
36680 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
36690 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
366a0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
366b0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
366c0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
366d0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
366e0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
366f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
36700 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
36710 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
36720 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
36730 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
36740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
36750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36760 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
36770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36780 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
36790 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
367a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
367b0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
367c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
367d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
367e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
367f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
36800 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
36810 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
36820 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
36830 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
36840 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36850 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
36860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36870 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
36880 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
36890 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
368a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
368b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
368c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
368d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
368e0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
368f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
36900 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
36910 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
36920 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36930 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
36940 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
36950 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36960 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
36970 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
36980 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
36990 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45  ent Object.** DE
369a0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
369b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
369c0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
369d0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
369e0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
369f0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
36a00 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
36a10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36a20 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
36a30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
36a40 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
36a50 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
36a60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
36a70 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
36a80 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
36a90 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
36aa0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
36ab0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
36ac0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
36ad0 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
36ae0 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
36af0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36b00 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
36b10 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
36b20 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
36b30 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
36b40 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
36b50 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36b60 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
36b70 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
36b80 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
36b90 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
36ba0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
36bb0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
36bc0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
36bd0 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
36be0 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
36bf0 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
36c00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
36c10 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
36c20 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
36c30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
36c40 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
36c50 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
36c60 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
36c70 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
36c80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
36c90 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
36ca0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
36cb0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
36cc0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
36cd0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
36ce0 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
36cf0 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
36d00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
36d10 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
36d20 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
36d30 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
36d40 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
36d50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36d60 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
36d70 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
36d80 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
36d90 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
36da0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
36db0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36dc0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36dd0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36de0 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
36df0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
36e00 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
36e10 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
36e20 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
36e30 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
36e40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
36e50 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
36e60 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
36e70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
36e80 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
36e90 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
36ea0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36eb0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
36ec0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
36ed0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36ee0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
36ef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36f00 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
36f10 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
36f20 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
36f30 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
36f40 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
36f50 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
36f60 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
36f70 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
36f80 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
36f90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
36fa0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
36fb0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
36fc0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
36fd0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
36fe0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
36ff0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
37000 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
37010 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
37020 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
37030 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
37040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
37050 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
37060 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
37070 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
37080 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
37090 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
370a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
370b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
370c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
370d0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
370e0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
370f0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
37100 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
37110 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
37120 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
37130 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
37140 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
37150 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
37160 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
37170 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
37180 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37190 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
371a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
371b0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
371c0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
371d0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
371e0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
371f0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
37200 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
37210 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
37220 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
37230 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
37240 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
37250 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
37260 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
37270 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
37280 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37290 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
372a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
372b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
372c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
372d0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
372e0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
372f0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
37300 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
37310 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
37320 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
37330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
37350 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
37360 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
37380 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37390 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
373a0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
373b0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
373c0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
373d0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
373e0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
373f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
37400 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
37410 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
37420 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
37430 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
37440 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
37450 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
37460 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
37470 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
37480 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
37490 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
374a0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
374b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
374c0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
374d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
374e0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
374f0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
37500 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
37510 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
37520 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
37530 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
37540 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
37550 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
37560 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
37570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
37580 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
37590 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
375a0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
375b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
375c0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
375d0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
375e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
375f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37600 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
37610 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
37620 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
37630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
37640 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
37650 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
37660 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
37670 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
37680 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
37690 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
376a0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
376b0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
376c0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
376d0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
376e0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
376f0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
37700 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
37710 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
37720 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
37730 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
37740 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
37750 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
37760 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
37770 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
37780 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
37790 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
377a0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
377b0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
377c0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
377d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
377e0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
377f0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
37800 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
37810 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
37820 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37830 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
37840 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
37850 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
37860 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
37870 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
37880 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
37890 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
378a0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
378b0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
378c0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
378d0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
378e0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
378f0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
37900 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
37910 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
37920 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
37930 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
37940 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
37950 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
37960 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
37970 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
37980 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
37990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
379a0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
379b0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
379c0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
379d0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
379e0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
379f0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
37a00 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
37a10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
37a20 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
37a30 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
37a40 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
37a50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
37a60 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
37a70 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
37a80 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
37a90 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37aa0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
37ab0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37ac0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
37ad0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
37ae0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
37af0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37b00 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
37b10 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
37b20 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
37b30 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
37b40 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
37b50 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
37b60 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
37b70 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
37b80 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
37b90 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
37ba0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37bb0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
37bc0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
37bd0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
37be0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
37bf0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
37c00 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
37c10 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
37c20 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
37c30 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
37c40 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
37c50 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
37c60 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
37c70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
37c80 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
37c90 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
37ca0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
37cb0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
37cc0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
37cd0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37ce0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
37cf0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
37d00 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
37d10 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
37d20 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
37d30 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
37d40 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
37d50 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
37d60 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
37d70 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
37d80 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
37d90 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
37da0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
37db0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
37dc0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
37dd0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
37de0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
37df0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
37e00 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
37e10 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
37e20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
37e30 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
37e40 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
37e50 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
37e60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
37e70 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
37e80 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
37e90 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
37ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
37eb0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
37ec0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
37ed0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
37ee0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
37ef0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
37f00 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
37f10 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
37f20 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
37f30 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
37f40 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
37f50 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
37f60 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
37f70 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
37f80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37f90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
37fa0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
37fb0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37fc0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37fd0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
37fe0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
37ff0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
38000 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
38010 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
38020 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
38030 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
38040 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
38050 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
38060 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
38070 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
38080 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
38090 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
380a0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
380b0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
380c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
380d0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
380e0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
380f0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
38100 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
38110 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
38120 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
38130 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
38140 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38150 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
38160 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
38170 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
38180 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
38190 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
381a0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
381b0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
381c0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
381d0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
381e0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
381f0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
38200 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
38210 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
38220 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
38230 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
38240 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
38250 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
38260 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38270 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
38280 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
38290 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
382a0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
382b0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
382c0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
382d0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
382e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
382f0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
38300 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
38310 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
38320 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
38330 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
38340 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38350 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
38360 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
38370 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
38380 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
38390 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
383a0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
383b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
383c0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
383d0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
383e0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
383f0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
38400 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
38410 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
38420 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
38430 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38440 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
38450 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
38460 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
38470 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
38480 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
38490 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
384a0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
384b0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
384c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
384d0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
384e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
384f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
38500 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
38510 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
38520 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
38530 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
38540 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
38550 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
38560 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
38570 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
38580 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
38590 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
385a0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
385b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
385c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
385d0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
385e0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
385f0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
38600 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
38610 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
38620 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
38630 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
38640 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
38650 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
38660 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
38670 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
38680 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
38690 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
386a0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
386b0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
386c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
386d0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
386e0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
386f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
38700 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
38710 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
38720 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
38730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38740 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
38750 72 20 72 65 73 6